Class: Lumberjack::Device::Buffer

Inherits:
Lumberjack::Device show all
Defined in:
lib/lumberjack/device/buffer.rb

Overview

A buffered logging device that wraps another logging device. Entries are buffered in memory until the buffer size is reached or the device is flushed.

Examples:

Create a buffered device that flushes every 5 entries

device = Lumberjack::Device::Buffer.new(Lumberjack::Device::LogFile.new("logfile.log"), buffer_size: 5)

Create a buffered device that automatically flushes every 10 seconds

device = Lumberjack::Device::Buffer.new("/var/log/app.log", buffer_size: 10, flush_seconds: 10)

Create a buffered device with a before_flush callback

before_flush = -> { puts "Flushing log buffer" }
device = Lumberjack::Device::Buffer.new(device, buffer_size: 10, before_flush: before_flush)

Defined Under Namespace

Classes: EntryBuffer

Instance Method Summary collapse

Methods inherited from Lumberjack::Device

#datetime_format, #datetime_format=, open_device

Constructor Details

#initialize(wrapped_device, options = {}) ⇒ Buffer

Initialize a new buffered logging device that wraps another device.

Parameters:

  • wrapped_device (Lumberjack::Device, String, Symbol, IO) —

    The underlying device to wrap. This can be any valid device specification that Lumberjack::Device.open_device accepts. Options not related to buffering will be passed to the underlying device constructor.

  • options (Hash) (defaults to: {}) —

    Options for the buffer and the underlying device.

Options Hash (options):

  • :buffer_size (Integer) —

    The number of entries to buffer before flushing. Default is 0 (no buffering).

  • :flush_seconds (Integer) —

    If specified, a background thread will flush the buffer every N seconds.

  • :before_flush (Proc) —

    A callback that will be called before each flush. The callback should respond to call and take no arguments.



114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/lumberjack/device/buffer.rb', line 114

def initialize(wrapped_device, options = {})
  buffer_options = [:buffer_size, :flush_seconds, :before_flush]
  device_options = options.reject { |k, _| buffer_options.include?(k) }
  device = Device.open_device(wrapped_device, device_options)

  @buffer = EntryBuffer.new(device, options[:buffer_size] || 0, options[:before_flush])

  flush_seconds = options[:flush_seconds]
  self.class.send(:create_flusher_thread, flush_seconds, @buffer) if flush_seconds.is_a?(Numeric) && flush_seconds > 0

  # Add a finalizer to ensure flush is called before the object is destroyed
  ObjectSpace.define_finalizer(self, self.class.send(:create_finalizer, @buffer))
end

Instance Method Details

#buffer_size ⇒ Object 



128
129
130
 
# File 'lib/lumberjack/device/buffer.rb', line 128

def buffer_size
  @buffer.size
end

#buffer_size=(value) ⇒ void

This method returns an undefined value.

Set the buffer size. The underlying device will only be written to when the buffer size is exceeded.

Parameters:

  • value (Integer) —

    The size of the buffer in bytes.



137
138
139
140
 
# File 'lib/lumberjack/device/buffer.rb', line 137

def buffer_size=(value)
  @buffer.size = value
  @buffer.flush
end

#close ⇒ void

This method returns an undefined value.

Close the device.



153
154
155
156
157
158
159
 
# File 'lib/lumberjack/device/buffer.rb', line 153

def close
  @buffer.close
  @buffer.device.close

  # Remove the finalizer since we've already flushed
  ObjectSpace.undefine_finalizer(self)
end

#closed? ⇒ Boolean

Return true if the buffer has been closed.

Returns:

  • (Boolean) 


162
163
164
 
# File 'lib/lumberjack/device/buffer.rb', line 162

def closed?
  @buffer.closed?
end

#dev ⇒ IO

Return the underlying stream. Provided for API compatibility with Logger devices.

Returns:

  • (IO) —

    The underlying stream.



184
185
186
 
# File 'lib/lumberjack/device/buffer.rb', line 184

def dev
  @buffer.device.dev
end

#empty? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (Boolean) 


194
195
196
 
# File 'lib/lumberjack/device/buffer.rb', line 194

def empty?
  @buffer.empty?
end

#flush ⇒ void

This method returns an undefined value.

Flush the buffer to the underlying device.



169
170
171
 
# File 'lib/lumberjack/device/buffer.rb', line 169

def flush
  @buffer.flush
end

#last_flushed_at ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



189
190
191
 
# File 'lib/lumberjack/device/buffer.rb', line 189

def last_flushed_at
  @buffer.last_flushed_at
end

#reopen(logdev = nil) ⇒ Object

Reopen the underlying device, optionally with a new log destination.



174
175
176
177
178
179
 
# File 'lib/lumberjack/device/buffer.rb', line 174

def reopen(logdev = nil)
  flush
  @buffer.device.reopen(logdev)
  @buffer.reopen
  ObjectSpace.define_finalizer(self, self.class.send(:create_finalizer, @buffer))
end

#write(entry) ⇒ void

This method returns an undefined value.

Write an entry to the underlying device.

Parameters:

  • entry (LogEntry, String) —

    The entry to write.



146
147
148
 
# File 'lib/lumberjack/device/buffer.rb', line 146

def write(entry)
  @buffer << entry
end