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:

Direct Known Subclasses

Buffer, LoggerWrapper, Multi, Null, Test, Writer

Defined Under Namespace

Classes: Buffer, DateRollingLogFile, LogFile, LoggerWrapper, Multi, Null, SizeRollingLogFile, 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))


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

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.



125
126
127
 
# File 'lib/lumberjack/device.rb', line 125

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.



155
156
 
# File 'lib/lumberjack/device.rb', line 155

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.



165
166
 
# File 'lib/lumberjack/device.rb', line 165

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.



172
173
174
 
# File 'lib/lumberjack/device.rb', line 172

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.



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

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.



136
137
138
 
# File 'lib/lumberjack/device.rb', line 136

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.

Raises:

  • (NotImplementedError) —

    If called on the abstract base class



115
116
117
 
# File 'lib/lumberjack/device.rb', line 115

def write(entry)
  raise NotImplementedError
end