This document provides a comprehensive overview of the Lumberjack logging framework architecture, illustrating how the various components work together to provide a flexible, high-performance logging solution for Ruby applications.
Lumberjack is a structured logging framework that extends Ruby's standard Logger with advanced features including:
- Structured logging with attributes (key-value pairs)
- Context isolation for scoping logging behavior
- Flexible output devices supporting files, streams, and custom destinations
- Customizable formatters for messages and attributes
- Thread and fiber safety for concurrent applications
- Hierarchical logger forking for component isolation
The framework follows a layered architecture with clear separation of concerns:
classDiagram
%% Core Logger Classes
class Logger {
+Device device
+Context context
+EntryFormatter formatter
+initialize(device, options)
+info(message, attributes)
+debug(message, attributes)
+error(message, attributes)
+add_entry(severity, message, progname, attributes)
+tag(attributes, &block)
+context(&block)
+fork(options) ForkedLogger
}
class ContextLogger {
<<interface>>
+level() Integer
+level=(value) void
+progname() String
+progname=(value) void
+add_entry(severity, message, progname, attributes)
+tag(attributes, &block)
+context(&block)
+attributes() Hash
}
class ForkedLogger {
+Logger parent_logger
+Context context
+initialize(parent_logger)
+add_entry(severity, message, progname, attributes)
}
%% Context and Attribute Management
class Context {
+Hash attributes
+Integer level
+String progname
+Integer default_severity
+initialize(parent_context)
+assign_attributes(attributes)
+clear_attributes()
}
class AttributesHelper {
+Hash attributes
+initialize(attributes)
+update(attributes)
+delete(*names)
+[](key) Object
+[]=(key, value)
}
%% Entry and Formatting
class LogEntry {
+Time time
+Integer severity
+String message
+String progname
+Integer pid
+Hash attributes
+initialize(time, severity, message, progname, pid, attributes)
+severity_label() String
+to_s() String
}
class EntryFormatter {
+Formatter message_formatter
+AttributeFormatter attribute_formatter
+format(message, attributes) Array
+format_class(classes, formatter, *args) self
+format_message(classes, formatter, *args) self
+format_attributes(classes, formatter, *args) self
+format_attribute_name(names, formatter, *args) self
+call(severity, timestamp, progname, msg) String
}
class Formatter {
+Hash class_formatters
+add(klass, formatter, *args, &block)
+remove(klass)
+format(message) Object
}
class AttributeFormatter {
+Hash attribute_formatters
+Formatter class_formatter
+Formatter default_formatter
+add(names_or_classes, formatter, *args, &block) self
+add_class(classes, formatter, *args, &block) self
+add_attribute(names, formatter, *args, &block) self
+default(formatter, *args, &block) self
+remove_class(classes) self
+remove_attribute(names) self
+format(attributes) Hash
+include_class?(class_or_name) Boolean
}
%% Device Architecture
class Device {
<<abstract>>
+write(entry) void
+flush() void
+close() void
+reopen(logdev) void
+datetime_format() String
+datetime_format=(format) void
}
class DeviceWriter["Device::Writer"] {
+IO stream
+Template template
+Buffer buffer
+initialize(stream, options)
+write(entry) void
+flush() void
+close() void
+reopen(logdev) void
+datetime_format() String
+datetime_format=(format) void
}
class DeviceLogFile["Device::LogFile"] {
+String path
+initialize(path, options)
+reopen(logdev) void
}
class DeviceDateRollingLogFile["Device::DateRollingLogFile"] {
+String path
+String frequency
+initialize(path, options)
+roll_file?() Boolean
}
class DeviceSizeRollingLogFile["Device::SizeRollingLogFile"] {
+String path
+Integer max_size
+Integer keep
+initialize(path, options)
+roll_file?() Boolean
}
class DeviceMulti["Device::Multi"] {
+Array devices
+initialize(*devices)
+write(entry) void
+flush() void
+close() void
+reopen(logdev) void
+datetime_format() String
+datetime_format=(format) void
}
class DeviceTest["Device::Test"] {
+Array entries
+Integer max_entries
+initialize(options)
+write(entry) void
+include?(options) Boolean
+match(**options) LogEntry
+clear() void
}
class DeviceNull["Device::Null"] {
+initialize()
+write(entry) void
}
class DeviceLoggerWrapper["Device::LoggerWrapper"] {
+Logger logger
+initialize(logger)
+write(entry) void
}
class DeviceBuffer["Device::Buffer"] {
+Array values
+Integer size
+initialize()
+<<(string) void
+empty?() Boolean
+pop!() Array
+clear() void
}
%% Template System
class Template {
+String template
+String time_format
+String attribute_format
+initialize(template, options)
+call(entry) String
}
%% Utility Classes
class Utils {
+deprecated(method, message, &block) Object
+hostname() String
+current_line() String
+flatten_attributes(hash) Hash
+expand_attributes(hash) Hash
+global_pid() String
+thread_name() String
+global_thread_id() String
}
class Severity {
+level_to_label(level) String
+label_to_level(label) Integer
+coerce(value) Integer
}
%% Relationships
Logger --|> ContextLogger : implements
ForkedLogger --|> Logger : inherits
Logger --* Device : uses
Logger --* Context : has
Logger --* EntryFormatter : uses
ForkedLogger --* Logger : forwards to
Context --* AttributesHelper : uses
EntryFormatter --* Formatter : uses
EntryFormatter --* AttributeFormatter : uses
AttributeFormatter --* Formatter : uses
Device <|-- DeviceWriter : implements
Device <|-- DeviceMulti : implements
Device <|-- DeviceTest : implements
Device <|-- DeviceNull : implements
Device <|-- DeviceLoggerWrapper : implements
DeviceWriter <|-- DeviceLogFile : inherits
DeviceLogFile <|-- DeviceDateRollingLogFile : inherits
DeviceLogFile <|-- DeviceSizeRollingLogFile : inherits
DeviceWriter --* Template : uses
DeviceWriter --* DeviceBuffer : uses
Logger --> LogEntry : creates
EntryFormatter --> LogEntry : processes
Device --> LogEntry : receives
DeviceMulti --* Device : aggregates
DeviceLoggerWrapper --* Logger : forwards to
DeviceTest --* LogEntry : stores
Logger
- Main entry point for logging operations
- Manages device, context, and formatting coordination
- Provides standard logging methods (info, debug, error, etc.)
- Handles context creation and attribute management
ContextLogger
- Mixin providing context-aware logging capabilities
- Manages level, progname, and attribute scoping
- Supports hierarchical contexts and attribute inheritance
- Thread and fiber-safe context isolation
ForkedLogger
- Creates isolated logger instances that forward to parent loggers
- Enables component-specific logging configuration
- Maintains independent context while sharing output infrastructure
Context
- Stores scoped logging configuration (level, progname, attributes)
- Supports hierarchical inheritance from parent contexts
- Provides isolation for block-scoped logging behavior
AttributesHelper
- Manages attribute hash manipulation and access
- Supports dot notation for nested attribute access
- Handles attribute merging and deletion operations
LogEntry
- Immutable data structure representing a single log event
- Contains all metadata: timestamp, severity, message, attributes
- Provides formatted string representation for output
EntryFormatter
- Coordinates message and attribute formatting
- Delegates to specialized formatters for different data types
- Handles complex formatting scenarios with embedded attributes
Formatter & AttributeFormatter
- Class-based and name-based formatting rules
- Recursive formatting for nested data structures
- Extensible formatting system with built-in formatters
Device (Abstract Base)
- Defines interface for log output destinations
- Supports lifecycle methods (flush, close, reopen)
- Enables pluggable output architecture
WriterDevice
- Writes formatted entries to IO streams
- Supports templated output formatting
- Handles encoding and error recovery
MultiDevice
- Broadcasts entries to multiple target devices
- Enables redundant logging and output splitting
- Maintains consistent state across all targets
Specialized Devices
- LogFileDevice: File-based logging with rotation
- TestDevice: In-memory capture for testing
- NullDevice: Silent operation for performance testing
- LoggerDevice: Forwards to other Logger instances
The following sequence diagram illustrates the complete flow of a log entry through the Lumberjack framework:
sequenceDiagram
participant App as Application
participant Logger as Logger
participant Context as Context
participant EntryFormatter as EntryFormatter
participant MsgFormatter as Message Formatter
participant AttrFormatter as Attribute Formatter
participant Device as Device
participant Template as Template
participant Output as Output Stream
%% Context Setup
App->>Logger: context do |ctx|
Logger->>Context: new(parent_context)
Context-->>Logger: context instance
App->>Logger: tag(user_id: 123)
Logger->>Context: assign_attributes({user_id: 123})
%% Logging Call
App->>Logger: info("User login", ip: "192.168.1.1")
Logger->>Logger: check level >= INFO
%% Entry Creation
Logger->>Logger: merge_all_attributes()
Note over Logger: Combines global, context, and local attributes
Logger->>LogEntry: new(time, severity, message, progname, pid, attributes)
LogEntry-->>Logger: entry instance
%% Entry Formatting
Logger->>EntryFormatter: format(message, attributes)
EntryFormatter->>MsgFormatter: format("User login")
MsgFormatter-->>EntryFormatter: formatted message
EntryFormatter->>AttrFormatter: format({user_id: 123, ip: "192.168.1.1"})
AttrFormatter-->>EntryFormatter: formatted attributes
EntryFormatter-->>Logger: [formatted_message, formatted_attributes]
%% Device Writing
Logger->>Device: write(entry)
alt WriterDevice
Device->>Template: call(entry)
Template-->>Device: formatted string
Device->>Output: write(formatted_string)
Output-->>Device: success
else MultiDevice
Device->>Device: devices.each
loop Each Target Device
Device->>Device: target.write(entry)
end
else TestDevice
Device->>Device: entries << entry
end
Device-->>Logger: success
Logger-->>App: true
%% Context Cleanup
Note over Logger,Context: Context automatically cleaned up when block exits