lumberjack 1.4.2 → 2.0.0

data/lib/lumberjack/entry_formatter.rb

@@ -0,0 +1,357 @@
+# frozen_string_literal: true
+
+module Lumberjack
+  # EntryFormatter provides a unified interface for formatting complete log entries by combining
+  # message formatting and attribute formatting into a single, coordinated system.
+  #
+  # This class serves as the central formatting coordinator in the Lumberjack logging pipeline,
+  # bringing together two specialized formatters:
+  # 1. Message Formatter ({Lumberjack::Formatter}) - Formats the main log message content
+  # 2. Attribute Formatter ({Lumberjack::AttributeFormatter}) - Formats key-value attribute pairs
+  #
+  # @example Complete entry formatting setup
+  #   entry_formatter = Lumberjack::EntryFormatter.build do |formatter|
+  #     # Formatter will be used in both log messages and attributes
+  #     formatter.format_class(ActiveRecord::Base, :id)
+  #
+  #     # Message specific formatters
+  #     formatter.format_message(Exception, :exception)
+  #     formatter.format_message(Time, :date_time, "%Y-%m-%d %H:%M:%S")
+  #
+  #     # Attribute specific formatters
+  #     formatter.format_attributes(Time, :date_time, "%Y-%m-%d")
+  #     formatter.format_attribute_name("password") { |value| "[REDACTED]" }
+  #     formatter.format_attribute_name("user_id", :id)
+  #     formatter.default_attribute_format { |value| value.to_s.strip }
+  #   end
+  #
+  # @example Using with a logger
+  #   logger = Lumberjack::Logger.new(STDOUT, formatter: entry_formatter)
+  #   logger.info("User login", user: user_object, timestamp: Time.now)
+  #   # Both the message and attributes are formatted according to the rules
+  #
+  # @see Lumberjack::Formatter
+  # @see Lumberjack::AttributeFormatter
+  # @see Lumberjack::Logger
+  class EntryFormatter
+    # The message formatter used to format log message content.
+    # @return [Lumberjack::Formatter] The message formatter instance.
+    attr_reader :message_formatter
+
+    # The attribute formatter used to format log entry attributes.
+    # @return [Lumberjack::AttributeFormatter] The attribute formatter instance.
+    attr_reader :attribute_formatter
+
+    class << self
+      # Build a new entry formatter using a configuration block. The block receives the new formatter
+      # as a parameter, allowing you to configure it with various configuration methods.
+      #
+      # @param message_formatter [Lumberjack::Formatter, Symbol, nil] The message formatter to use.
+      #   Can be a Formatter instance, :default for standard formatter, :none for empty formatter, or nil.
+      # @param attribute_formatter [Lumberjack::AttributeFormatter, nil] The attribute formatter to use.
+      # @yield [formatter] A block that configures the entry formatter.
+      # @return [Lumberjack::EntryFormatter] A new configured entry formatter.
+      #
+      # @example
+      #   formatter = Lumberjack::EntryFormatter.build do |config|
+      #     config.add(User, :id)  # Message formatting
+      #     config.add(Time, :date_time, "%Y-%m-%d")
+      #
+      #     config.add_attribute("password") { "[REDACTED]" } # ensure passwords are not logged
+      #     config.add_attribute_class(Exception) { |e| {error: e.class.name, message: e.message} }
+      #   end
+      def build(message_formatter: nil, attribute_formatter: nil, &block)
+        formatter = new(message_formatter: message_formatter, attribute_formatter: attribute_formatter)
+        block&.call(formatter)
+        formatter
+      end
+    end
+
+    # Create a new entry formatter with the specified message and attribute formatters.
+    #
+    # @param message_formatter [Lumberjack::Formatter, Symbol, nil] The message formatter to use:
+    #   - Formatter instance: Used directly
+    #   - :default or nil: Creates a new Formatter with default mappings
+    #   - :none: Creates an empty Formatter with no default mappings
+    # @param attribute_formatter [Lumberjack::AttributeFormatter, nil] The attribute formatter to use.
+    #   If nil, no attribute formatting will be performed unless configured later.
+    def initialize(message_formatter: nil, attribute_formatter: nil)
+      self.message_formatter = message_formatter
+      self.attribute_formatter = attribute_formatter
+    end
+
+    # Set the message formatter used to format log message content.
+    #
+    # @param value [Lumberjack::Formatter, Symbol, nil] The message formatter to use. If the value
+    #   is :default, a standard formatter with default mappings is created. If nil, a new empty
+    #   formatter is created.
+    # @return [void]
+    def message_formatter=(value)
+      @message_formatter = if value == :default
+        Lumberjack::Formatter.default
+      elsif value.nil?
+        Lumberjack::Formatter.new
+      else
+        value
+      end
+    end
+
+    # Set the attribute formatter used to format log entry attributes.
+    #
+    # @param value [Lumberjack::AttributeFormatter, nil] The attribute formatter to use.
+    #   If nil, a new empty AttributeFormatter is created.
+    # @return [void]
+    def attribute_formatter=(value)
+      @attribute_formatter = value || AttributeFormatter.new
+    end
+
+    # Add a formatter for specific classes or modules. This method adds the formatter
+    # for both log messages and attributes.
+    #
+    # @param classes_or_names [Class, Module, String, Array<Class, Module, String>] The class(es) to format.
+    # @param formatter [Symbol, Class, #call, nil] The formatter to use.
+    # @param args [Array] Arguments to pass to the formatter constructor (when formatter is a Class).
+    # @yield [obj] Block-based formatter that receives the object to format.
+    # @return [Lumberjack::EntryFormatter] Returns self for method chaining.
+    #
+    # @example Adding formatters
+    #   formatter.format_class(User, :id)  # Use ID formatter for User objects
+    #   formatter.format_class(Array) { |vals| vals.join(", ") }  # Handle arrays
+    #   formatter.format_class(Time, :date_time, "%Y-%m-%d")  # Custom time format only
+    #
+    # @see Lumberjack::Formatter#add
+    def format_class(classes_or_names, formatter = nil, *args, &block)
+      Array(classes_or_names).each do |class_or_name|
+        unless @message_formatter.include?(class_or_name)
+          @message_formatter.add(class_or_name, formatter, *args, &block)
+        end
+
+        unless @attribute_formatter.include_class?(class_or_name)
+          @attribute_formatter.add_class(class_or_name, formatter, *args, &block)
+        end
+      end
+
+      self
+    end
+
+    # Remove a formatter for specific classes or modules. This method removes the formatter
+    # for both log messages and attributes.
+    #
+    # @param classes_or_names [Class, Module, String, Array<Class, Module, String>] The class(es) to remove formatters for.
+    # @return [Lumberjack::EntryFormatter] Returns self for method chaining.
+    #
+    # @see Lumberjack::Formatter#remove
+    def remove_class(classes_or_names)
+      @message_formatter.remove(classes_or_names)
+      @attribute_formatter.remove_class(classes_or_names)
+      self
+    end
+
+    # Add a message formatter for specific classes or modules.
+    #
+    # @param classes_or_names [String, Module, Array<String, Module>] Class names or modules.
+    # @param formatter [Symbol, Class, #call, nil] The formatter to use
+    # @param args [Array] Arguments to pass to the formatter constructor (when formatter is a Class).
+    # @yield [obj] Block-based formatter that receives the object to format.
+    # @return [Lumberjack::EntryFormatter] Returns self for method chaining.
+    #
+    # @see Lumberjack::Formatter#add
+    def format_message(classes_or_names, formatter = nil, *args, &block)
+      @message_formatter.add(classes_or_names, formatter, *args, &block)
+      self
+    end
+
+    # Remove a message formatter for specific classes or modules.
+    #
+    # @param classes_or_names [String, Module, Array<String, Module>] Class names or modules.
+    # @return [Lumberjack::EntryFormatter] Returns self for method chaining.
+    #
+    # @see Lumberjack::Formatter#remove
+    def remove_message_formatter(classes_or_names)
+      @message_formatter.remove(classes_or_names)
+      self
+    end
+
+    # Add a formatter for the named attribute.
+    #
+    # @param names [String, Symbol, Array<String, Symbol>] The attribute names to format.
+    # @param formatter [Symbol, Class, #call, nil] The formatter to use
+    # @param args [Array] Arguments to pass to the formatter constructor (when formatter is a Class).
+    # @yield [value] Block-based formatter that receives the attribute value.
+    # @return [Lumberjack::EntryFormatter] Returns self for method chaining.
+    #
+    # @see Lumberjack::AttributeFormatter#add_attribute
+    def format_attribute_name(names, formatter = nil, *args, &block)
+      @attribute_formatter.add_attribute(names, formatter, *args, &block)
+      self
+    end
+
+    # Add a formatter for the specified class or module when it appears as an attribute value.
+    #
+    # @param classes_or_names [String, Module, Array<String, Module>] Class names or modules.
+    # @param formatter [Symbol, Class, #call, nil] The formatter to use
+    # @param args [Array] Arguments to pass to the formatter constructor (when formatter is a Class).
+    # @yield [value] Block-based formatter that receives the attribute value.
+    # @return [Lumberjack::EntryFormatter] Returns self for method chaining.
+    #
+    # @see Lumberjack::AttributeFormatter#add_attribute
+    def format_attributes(classes_or_names, formatter = nil, *args, &block)
+      @attribute_formatter.add_class(classes_or_names, formatter, *args, &block)
+      self
+    end
+
+    # Set the default attribute formatter to apply to any attributes that do not
+    # have a specific formatter defined.
+    #
+    # @param formatter [Symbol, Class, #call, nil] The default formatter to use.
+    #   If nil, removes any existing default formatter.
+    # @param args [Array] Arguments to pass to the formatter constructor (when formatter is a Class).
+    # @yield [value] Block-based formatter that receives the attribute value.
+    # @return [Lumberjack::EntryFormatter] Returns self for method chaining.
+    #
+    # @see Lumberjack::AttributeFormatter#default
+    def default_attribute_format(formatter = nil, *args, &block)
+      @attribute_formatter.default(formatter, *args, &block)
+      self
+    end
+
+    # Remove an attribute formatter for the specified attribute names.
+    #
+    # @param names [String, Symbol, Array<String, Symbol>] The attribute names to remove formatters for.
+    # @return [Lumberjack::EntryFormatter] Returns self for method chaining.
+    #
+    # @see Lumberjack::AttributeFormatter#remove_attribute
+    def remove_attribute_name(names)
+      @attribute_formatter.remove_attribute(names)
+      self
+    end
+
+    # Remove an attribute formatter for the specified classes or modules.
+    #
+    # @param classes_or_names [String, Module, Array<String, Module>] Class names or modules.
+    # @return [Lumberjack::EntryFormatter] Returns self for method chaining.
+    #
+    # @see Lumberjack::AttributeFormatter#remove_class
+    def remove_attribute_class(classes_or_names)
+      @attribute_formatter.remove_class(classes_or_names)
+      self
+    end
+
+    # Extend this formatter by adding the formats defined in the provided formatter into this one.
+    #
+    # @param formatter [Lumberjack::EntryFormatter] The formatter to merge.
+    # @return [self] Returns self for method chaining.
+    def include(formatter)
+      unless formatter.is_a?(Lumberjack::EntryFormatter)
+        raise ArgumentError.new("formatter must be a Lumberjack::EntryFormatter")
+      end
+
+      @message_formatter ||= Lumberjack::Formatter.new
+      @message_formatter.include(formatter.message_formatter)
+
+      @attribute_formatter ||= Lumberjack::AttributeFormatter.new
+      @attribute_formatter.include(formatter.attribute_formatter)
+
+      self
+    end
+
+    # Extend this formatter by adding the formats defined in the provided formatter into this one.
+    # Formats defined in this formatter will take precedence and not be overridden.
+    #
+    # @param formatter [Lumberjack::EntryFormatter] The formatter to merge.
+    # @return [self] Returns self for method chaining.
+    def prepend(formatter)
+      unless formatter.is_a?(Lumberjack::EntryFormatter)
+        raise ArgumentError.new("formatter must be a Lumberjack::EntryFormatter")
+      end
+
+      @message_formatter ||= Lumberjack::Formatter.new
+      @message_formatter.prepend(formatter.message_formatter)
+
+      @attribute_formatter ||= Lumberjack::AttributeFormatter.new
+      @attribute_formatter.prepend(formatter.attribute_formatter)
+
+      self
+    end
+
+    # Format a complete log entry by applying both message and attribute formatting.
+    # This is the main method that coordinates the formatting of both the message content
+    # and any associated attributes.
+    #
+    # @param message [Object, Proc, nil] The log message to format. Can be any object, a Proc that returns the message, or nil.
+    # @param attributes [Hash, nil] The log entry attributes to format.
+    # @return [Array<Object, Hash>] A two-element array containing [formatted_message, formatted_attributes].
+    def format(message, attributes)
+      message = message.call if message.is_a?(Proc)
+      message = message_formatter.format(message) if message_formatter.respond_to?(:format)
+
+      message_attributes = nil
+      if message.is_a?(MessageAttributes)
+        message_attributes = message.attributes
+        message = message.message
+      end
+      message_attributes = Utils.flatten_attributes(message_attributes) if message_attributes
+
+      attributes = merge_attributes(attributes, message_attributes) if message_attributes
+      attributes = AttributesHelper.expand_runtime_values(attributes)
+      attributes = attribute_formatter.format(attributes) if attributes && attribute_formatter
+
+      [message, attributes]
+    end
+
+    # Compatibility method for Ruby's standard Logger::Formatter interface. This delegates
+    # to the message formatter's call method for basic Logger compatibility.
+    #
+    # @param severity [Integer, String, Symbol] The log severity (passed to message formatter).
+    # @param timestamp [Time] The log timestamp (passed to message formatter).
+    # @param progname [String] The program name (passed to message formatter).
+    # @param msg [Object] The message object to format (passed to message formatter).
+    # @return [String, nil] The formatted message string, or nil if no message formatter.
+    #
+    # @see Lumberjack::Formatter#call
+    def call(severity, timestamp, progname, msg)
+      message_formatter&.call(severity, timestamp, progname, msg)
+    end
+
+    private
+
+    # Merge two attribute hashes, handling nil values gracefully.
+    # Used to combine explicit log attributes with attributes embedded in MessageAttributes objects.
+    #
+    # @param current_attributes [Hash, nil] The primary attributes hash.
+    # @param attributes [Hash, nil] Additional attributes to merge in.
+    # @return [Hash, nil] The merged attributes hash, or nil if both inputs are nil/empty.
+    # @api private
+    def merge_attributes(current_attributes, attributes)
+      if current_attributes.nil? || current_attributes.empty?
+        attributes
+      elsif attributes.nil?
+        current_attributes
+      else
+        current_attributes.merge(attributes)
+      end
+    end
+
+    # Check if a formatter accepts an attributes parameter in its call method.
+    # This is used for determining formatter compatibility but is currently unused (TODO).
+    #
+    # @param formatter [#call] The formatter to check.
+    # @return [Boolean] true if the formatter accepts 5+ parameters or has a splat parameter.
+    # @api private
+    # @todo This method needs to be integrated into the logger functionality.
+    def accepts_attributes_parameter?(formatter)
+      method_obj = if formatter.is_a?(Proc)
+        formatter
+      elsif formatter.respond_to?(:call)
+        formatter.method(:call)
+      end
+      return false unless method_obj
+
+      params = method_obj.parameters
+      positional = params.slice(:req, :opt)
+      has_splat = params.any? { |type, _| type == :rest }
+      positional_count = positional.size
+      positional_count >= 5 || has_splat
+    end
+  end
+end

data/lib/lumberjack/fiber_locals.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Lumberjack
+  # Provides isolated fiber-local storage for thread-safe data access.
+  module FiberLocals
+    # Lightweight structure to hold fiber-local data.
+    #
+    # @api private
+    class Data
+      attr_accessor :context, :logging, :cleared
+
+      def initialize(copy = nil)
+        @context = copy&.context
+        @logging = copy&.logging
+        @cleared = copy&.cleared
+      end
+    end
+
+    private
+
+    def fiber_locals(&block)
+      init_fiber_locals! unless defined?(@fiber_locals)
+
+      fiber_id = Fiber.current.object_id
+      current = @fiber_locals[fiber_id]
+      data = Data.new(current)
+      begin
+        @fiber_locals_mutex.synchronize do
+          @fiber_locals[fiber_id] = data
+        end
+        yield data
+      ensure
+        @fiber_locals_mutex.synchronize do
+          if current.nil?
+            @fiber_locals.delete(fiber_id)
+          else
+            @fiber_locals[fiber_id] = current
+          end
+        end
+      end
+    end
+
+    def fiber_local
+      return nil unless defined?(@fiber_locals)
+
+      @fiber_locals[Fiber.current.object_id]
+    end
+
+    # Initialize the fiber locals storage and mutex.
+    def init_fiber_locals!
+      @fiber_locals ||= {}
+      @fiber_locals_mutex ||= Mutex.new
+    end
+  end
+end

data/lib/lumberjack/forked_logger.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Lumberjack
+  # ForkedLogger provides an isolated logging context that forwards all log entries to a parent logger
+  # while maintaining its own independent configuration (level, progname, attributes).
+  #
+  # This class allows you to create specialized logger instances that:
+  # - Inherit initial configuration from a parent logger
+  # - Maintain isolated settings (level, progname, attributes) that don't affect the parent
+  # - Forward all log entries to the parent logger's output device
+  # - Combine their own attributes with the parent logger's attributes
+  # - Provide scoped logging behavior without duplicating output infrastructure
+  #
+  # ForkedLogger is particularly useful for:
+  #
+  # - Component isolation: Give each component its own logger with specific attributes
+  # - Request tracing: Create request-specific loggers with request IDs
+  # - Temporary debugging: Create debug-level loggers for specific code paths
+  # - Library integration: Allow libraries to have their own logging configuration
+  # - Multi-tenant logging: Isolate tenant-specific logging configuration
+  #
+  # The forked logger inherits the parent's initial state but changes are isolated:
+  #
+  # - Inherited: Initial level, progname, and device (through forwarding)
+  # - Isolated: subsequent changes to level, progname, and attributes do not affect the parent logger
+  # - Combined: attributes from the parent and the forked loggers are merged when logging
+  #
+  # @example Basic forked logger
+  #   parent = Lumberjack::Logger.new(STDOUT, level: :info)
+  #   forked = Lumberjack::ForkedLogger.new(parent)
+  #   forked.level = :debug  # Only affects the forked logger
+  #   forked.debug("Debug message")  # Logged because forked logger is debug level
+  #
+  # @example Component-specific logging
+  #   main_logger = Lumberjack::Logger.new("/var/log/app.log")
+  #   db_logger = Lumberjack::ForkedLogger.new(main_logger)
+  #   db_logger.progname = "Database"
+  #   db_logger.tag!(component: "database", version: "1.2.3")
+  #   db_logger.info("Connection established")  # Includes component attributes and different progname
+  #
+  # @example Request-scoped logging
+  #   def handle_request(request_id)
+  #     request_logger = Lumberjack::ForkedLogger.new(@logger)
+  #     request_logger.tag!(request_id: request_id, user_id: current_user.id)
+  #
+  #     request_logger.info("Processing request")  # Includes request context
+  #     # ... process request ...
+  #     request_logger.info("Request completed")   # All logs tagged with request info
+  #   end
+  #
+  # @see Lumberjack::Logger
+  # @see Lumberjack::ContextLogger
+  # @see Lumberjack::Context
+  class ForkedLogger < Logger
+    include ContextLogger
+
+    # The parent logger that receives all log entries from this forked logger.
+    # @return [Lumberjack::Logger, #add_entry] The parent logger instance.
+    attr_reader :parent_logger
+
+    # Create a new forked logger that forwards all log entries to the specified parent logger.
+    # The forked logger inherits the parent's initial level and progname but maintains
+    # its own independent context for future changes.
+    #
+    # @param logger [Lumberjack::ContextLogger, #add_entry] The parent logger to forward entries to.
+    #   Must respond to either +add_entry+ (for Lumberjack loggers) or standard Logger methods.
+    def initialize(logger)
+      init_fiber_locals!
+      @parent_logger = logger
+      @context = Context.new
+      @context.level ||= logger.level
+      @context.progname ||= logger.progname
+    end
+
+    # Forward a log entry to the parent logger with the forked logger's configuration applied.
+    # This method coordinates between the forked logger's settings and the parent logger's
+    # output capabilities.
+    #
+    # @param severity [Integer, Symbol, String] The severity level of the log entry.
+    # @param message [Object] The message to log.
+    # @param progname [String, nil] The program name (defaults to this logger's progname).
+    # @param attributes [Hash, nil] Additional attributes to include with the log entry.
+    # @return [Boolean] Returns the result of the parent logger's logging operation.
+    #
+    # @api private
+    def add_entry(severity, message, progname = nil, attributes = nil)
+      parent_logger.with_level(level || Logger::DEBUG) do
+        attributes = merge_attributes(attributes, local_attributes)
+        progname ||= self.progname
+
+        if parent_logger.is_a?(ContextLogger)
+          parent_logger.add_entry(severity, message, progname, attributes)
+        else
+          parent_logger.tag(attributes) do
+            parent_logger.add(severity, message, progname)
+          end
+        end
+      end
+    end
+
+    # Flush any buffered log entries in the parent logger's device.
+    #
+    # @return [void]
+    def flush
+      parent_logger.flush
+    end
+
+    # Return the log device of the parent logger, if available.
+    #
+    # @return [Lumberjack::Device] The parent logger's output device.
+    def device
+      parent_logger.device if parent_logger.respond_to?(:device)
+    end
+
+    # Return the formatter of the parent logger, if available.
+    #
+    # @return [Lumberjack::EntryFormatter] The parent logger's formatter.
+    def formatter
+      parent_logger.formatter if parent_logger.respond_to?(:formatter)
+    end
+
+    private
+
+    # Return the default context for this forked logger. This provides the isolated
+    # configuration context that doesn't affect the parent logger.
+    #
+    # @return [Lumberjack::Context] The forked logger's private context.
+    # @api private
+    def default_context
+      @context
+    end
+
+    # Merge all attributes that should be included with log entries from this forked logger.
+    # This combines the default context attributes (set with tag!) and any local context
+    # attributes (set within context blocks).
+    #
+    # @return [Hash, nil] The merged attributes hash, or nil if no attributes are set.
+    # @api private
+    def local_attributes
+      merge_attributes(default_context&.attributes, local_context&.attributes)
+    end
+  end
+end

data/lib/lumberjack/formatter/date_time_formatter.rb

@@ -2,16 +2,27 @@
 
 module Lumberjack
   class Formatter
-    # Format a Date, Time, or DateTime object. If you don't specify a format in the constructor,
-    # it will use the ISO-8601 format.
+    # Format a Date, Time, or DateTime object. If you don't specify a format in the constructor, it will use
+    # the ISO-8601 format with microsecond precision. This formatter provides consistent date/time representation
+    # across your application logs.
     class DateTimeFormatter
+      FormatterRegistry.add(:date_time, self)
+
+      # @!attribute [r] format
+      #   @return [String, nil] The strftime format string, or nil for ISO-8601 default.
       attr_reader :format
 
-      # @param [String] format The format to use when formatting the date/time object.
+      # @param format [String, nil] The format to use when formatting the date/time object.
+      #   If nil, uses ISO-8601 format with microsecond precision.
       def initialize(format = nil)
         @format = format.dup.to_s.freeze unless format.nil?
       end
 
+      # Format a date/time object using the configured format.
+      #
+      # @param obj [Date, Time, DateTime, Object] The object to format. Should respond to
+      #   strftime (for custom format) or iso8601 (for default format).
+      # @return [String] The formatted date/time string.
       def call(obj)
         if @format && obj.respond_to?(:strftime)
           obj.strftime(@format)

data/lib/lumberjack/formatter/exception_formatter.rb

@@ -3,18 +3,28 @@
 module Lumberjack
   class Formatter
     # Format an exception including the backtrace. You can specify an object that
-    # responds to `call` as a backtrace cleaner. The exception backtrace will be
+    # responds to +call+ as a backtrace cleaner. The exception backtrace will be
     # passed to this object and the returned array is what will be logged. You can
     # use this to clean out superfluous lines.
     class ExceptionFormatter
+      FormatterRegistry.add(:exception, self)
+
+      # @!attribute [rw] backtrace_cleaner
+      #   @return [#call, nil] An object that responds to +call+ and takes
+      #     an array of strings (the backtrace) and returns an array of strings.
       attr_accessor :backtrace_cleaner
 
-      # @param [#call] backtrace_cleaner An object that responds to `call` and takes
+      # @param backtrace_cleaner [#call, nil] An object that responds to +call+ and takes
       #   an array of strings (the backtrace) and returns an array of strings (the
+      #   cleaned backtrace).
       def initialize(backtrace_cleaner = nil)
         self.backtrace_cleaner = backtrace_cleaner
       end
 
+      # Format an exception with its message and backtrace.
+      #
+      # @param exception [Exception] The exception to format.
+      # @return [String] The formatted exception with class name, message, and backtrace.
       def call(exception)
         message = +"#{exception.class.name}: #{exception.message}"
         trace = exception.backtrace

data/lib/lumberjack/formatter/id_formatter.rb

@@ -5,12 +5,24 @@ module Lumberjack
     # Format an object that has an id as a hash with keys for class and id. This formatter is useful
     # as a default formatter for objects pulled from a data store. By default it will use :id as the
     # id attribute.
+    #
+    # The formatter creates a standardized representation of objects by extracting their class name
+    # and identifier, making it easy to identify objects in logs without exposing all their data.
+    # This is particularly useful for ActiveRecord models, database objects, or any objects that
+    # have a unique identifier attribute.
     class IdFormatter
-      # @param [Symbol, String] id_attribute The attribute to use as the id.
+      FormatterRegistry.add(:id, self)
+
+      # @param id_attribute [Symbol, String] The attribute to use as the id (defaults to :id).
       def initialize(id_attribute = :id)
         @id_attribute = id_attribute
       end
 
+      # Format an object by extracting its class name and ID attribute.
+      #
+      # @param obj [Object] The object to format. Must respond to the configured ID attribute.
+      # @return [Hash, String] A hash with "class" and "id" keys if the object has the ID attribute,
+      #   otherwise returns the object's string representation.
       def call(obj)
         if obj.respond_to?(@id_attribute)
           id = obj.send(@id_attribute)

data/lib/lumberjack/formatter/inspect_formatter.rb

@@ -2,8 +2,21 @@
 
 module Lumberjack
   class Formatter
-    # Format an object by calling +inspect+ on it.
+    # Format an object by calling +inspect+ on it. This formatter provides
+    # a debugging-friendly representation of objects, showing their internal
+    # structure and contents in a readable format.
+    #
+    # The InspectFormatter is particularly useful for logging complex objects
+    # where you need to see their complete state, such as arrays, hashes,
+    # or custom objects. It relies on Ruby's built-in +inspect+ method,
+    # which provides detailed object representations.
     class InspectFormatter
+      FormatterRegistry.add(:inspect, self)
+
+      # Convert an object to its inspect representation.
+      #
+      # @param obj [Object] The object to format.
+      # @return [String] The inspect representation of the object.
       def call(obj)
         obj.inspect
       end