Class: Lumberjack::Device Abstract

Inherits:
Object
  • Object
show all
Defined in:
lib/lumberjack/device.rb

Overview

This class is abstract.

Subclass and implement #write to create a concrete device

Abstract base class defining the interface for logging output devices. Devices are responsible for the final output of log entries to various destinations such as files, streams, databases, or external services.

This class establishes the contract that all concrete device implementations must follow, with the write method being the only required implementation. Additional lifecycle methods (+close+, flush, reopen) and configuration methods (+datetime_format+) are optional but provide standardized interfaces for device management.

The device architecture allows for flexible log output handling while maintaining consistent behavior across different output destinations. Devices receive formatted LogEntry objects and are responsible for their final serialization and delivery.

See Also:

Defined Under Namespace

Classes: Buffer, LogFile, LoggerWrapper, Multi, Null, Test, Writer

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.open_device(device, options = {}) ⇒ Lumberjack::Device

Open a logging device with the given options.

Examples:

Open a file-based device

device = Lumberjack::Device.open_device("/var/log/myapp.log", shift_age: "daily")

Open a stream-based device

device = Lumberjack::Device.open_device($stdout)

Open a device from the registry

device = Lumberjack::Device.open_device(:syslog)

Open multiple devices

device = Lumberjack::Device.open_device([["/var/log/app.log", {shift_age: "daily"}], $stdout])

Wrap another logger

device = Lumberjack::Device.open_device(Lumberjack::Logger.new($stdout))

Parameters:

  • device (nil, Symbol, String, File, IO, Array, Lumberjack::Device, ContextLogger) —

    The device to open. The device can be:

    • nil: returns a Device::Null instance that discards all log entries.
    • Symbol: looks up the device in the DeviceRegistry and creates a new instance with the provided options.
    • String or Pathname: treated as a file path and opens a Device::LogFile.
    • File: opens a Device::LogFile for the given file stream.
    • IO: opens a Device::Writer wrapping the given IO stream.
    • Lumberjack::Device: returns the device instance as-is.
    • ContextLogger: wraps the logger in a Device::LoggerWrapper.
    • Array: each element is treated as a device specification and opened recursively, returning a Device::Multi that routes log entries to all specified devices. Each device can have its own options hash if passed as a two-element array [device, options].
  • options (Hash) (defaults to: {}) —

    Options to pass to the device constructor.

Returns:



68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/lumberjack/device.rb', line 68

def open_device(device, options = {})
  device = device.to_s if device.is_a?(Pathname)

  if device.nil?
    Device::Null.new
  elsif device.is_a?(Device)
    device
  elsif device.is_a?(Symbol)
    DeviceRegistry.new_device(device, options)
  elsif device.is_a?(ContextLogger) || device.is_a?(::Logger)
    Device::LoggerWrapper.new(device)
  elsif device.is_a?(Array)
    devices = device.collect do |dev, dev_options|
      dev_options = dev_options.is_a?(Hash) ? options.merge(dev_options) : options
      open_device(dev, dev_options)
    end
    Device::Multi.new(devices)
  elsif io_but_not_file_stream?(device)
    Device::Writer.new(device, options)
  else
    Device::LogFile.new(device, options)
  end
end

Instance Method Details

#close ⇒ void

This method returns an undefined value.

Close the device and release any resources. The default implementation calls flush to ensure any buffered data is written before closing. Subclasses should override this method if they need to perform specific cleanup operations such as closing file handles or network connections.



123
124
125
 
# File 'lib/lumberjack/device.rb', line 123

def close
  flush
end

#datetime_format ⇒ String?

Get the current datetime format string used for timestamp formatting. The default implementation returns nil, indicating no specific format is set. Subclasses may override this to provide device-specific timestamp formatting.

Returns:

  • (String, nil) —

    The datetime format string, or nil if not set



153
154
 
# File 'lib/lumberjack/device.rb', line 153

def datetime_format
end

#datetime_format=(format) ⇒ void

This method returns an undefined value.

Set the datetime format string for timestamp formatting. The default implementation is a no-op. Subclasses that support configurable timestamp formatting should override this method to store and apply the specified format.

Parameters:

  • format (String, nil) —

    The datetime format string to use for timestamps



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

def datetime_format=(format)
end

#dev ⇒ IO, ...

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.

Expose the underlying stream if any.

Returns:

  • (IO, Lumberjacke::Device, nil) 


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

def dev
  self
end

#flush ⇒ void

This method returns an undefined value.

Flush any buffered data to the output destination. The default implementation is a no-op since not all devices use buffering. Subclasses that implement buffering should override this method to ensure data is written to the final destination.



144
145
 
# File 'lib/lumberjack/device.rb', line 144

def flush
end

#reopen(logdev = nil) ⇒ void

This method returns an undefined value.

Reopen the device, optionally with a new log destination. The default implementation calls flush to ensure data consistency. This method is typically used for log rotation scenarios or when changing output destinations dynamically.

Parameters:

  • logdev (Object, nil) (defaults to: nil) —

    Optional new log device or destination



134
135
136
 
# File 'lib/lumberjack/device.rb', line 134

def reopen(logdev = nil)
  flush
end

#write(entry) ⇒ void

This method is abstract.

Subclasses must implement this method

This method returns an undefined value.

Write a log entry to the device. This is the core method that all device implementations must provide. The method receives a fully formatted LogEntry object and is responsible for outputting it to the target destination.

Parameters:

Raises:

  • (NotImplementedError) —

    If called on the abstract base class



113
114
115
 
# File 'lib/lumberjack/device.rb', line 113

def write(entry)
  raise NotImplementedError
end