betterlog 2.0.6 → 2.1.1

data/lib/betterlog/global_metadata.rb

@@ -4,22 +4,61 @@
 # tools etc.
 
 module Betterlog
+
+  # Thread-local storage for global metadata used to enrich log events.
+  #
+  # This class provides a thread-safe mechanism to store and manage metadata
+  # that should be included with log events. It ensures that metadata is
+  # scoped to the current thread and can be easily added, removed, or
+  # temporarily applied within a block context.
+  #
+  # @see Betterlog::Log::Event
+  # @see Betterlog.with_meta
   class GlobalMetadata
     include Tins::SexySingleton
 
     thread_local(:current) { {} }
 
+    # Adds metadata to the current thread-local storage.
+    #
+    # This method takes a hash of data and merges it with the existing metadata
+    # in the current thread's storage. The provided data is symbolized and then
+    # combined with the current metadata using a union operation, ensuring that
+    # new keys overwrite existing ones with the same name.
+    #
+    # @param data [ Hash ] A hash containing the metadata to be added
+    # @return [ Betterlog::GlobalMetadata ] Returns the GlobalMetadata instance itself
     def add(data)
       data = data.symbolize_keys_recursive
       self.current = data | current
       self
     end
 
+    # Removes metadata keys from the current thread-local storage.
+    #
+    # This method takes a hash or array of keys and deletes the corresponding
+    # entries from the global metadata stored in the current thread. It ensures
+    # that only the specified keys are removed, leaving other metadata intact.
+    #
+    # @param data [ Hash, Array ] A hash containing keys to remove or an array
+    # of key symbols
+    # @return [ void ] Returns nil after removing the specified keys
     def remove(data)
       keys = data.ask_and_send_or_self(:keys).map(&:to_sym)
       keys.each { current.delete(_1) }
     end
 
+    # Temporarily adds metadata to the current thread-local storage for the
+    # duration of a block execution.
+    #
+    # This method allows for the temporary addition of metadata to the global
+    # metadata store within the context of a block. The metadata is
+    # automatically removed after the block completes, ensuring that the
+    # metadata changes do not persist beyond the intended scope.
+    #
+    # @param data [ Hash ] A hash containing the metadata key-value pairs to be added
+    # @yield [ data ] Executes the provided block with the metadata in place
+    # @return [ void ] Returns nil after the block has been executed and metadata removed
     def with_meta(data = {}, &block)
       add data
       block.call
@@ -28,6 +67,16 @@ module Betterlog
     end
   end
 
+  # Provides a convenient way to temporarily add metadata to the global
+  # metadata store within the scope of a block.
+  #
+  # This method serves as a shortcut to Betterlog::GlobalMetadata.with_meta,
+  # allowing for easy temporary addition of metadata that is automatically
+  # removed after the block execution completes.
+  #
+  # @param data [ Hash ] A hash containing the metadata key-value pairs to be added
+  # @yield [ data ] Executes the provided block with the metadata in place
+  # @return [ void ] Returns nil after the block has been executed and metadata removed
   def self.with_meta(data = {}, &block)
     Betterlog::GlobalMetadata.with_meta(data, &block)
   end

data/lib/betterlog/log/event.rb

@@ -1,8 +1,30 @@
+require 'socket'
+
 module Betterlog
   class Log
+    # A structured logging event representation.
+    #
+    # This class encapsulates log event data with standardized formatting and
+    # metadata enrichment. It provides methods for creating, formatting, and
+    # serializing log events while ensuring consistent structure and
+    # compatibility with various logging systems.
+    #
+    # @see Betterlog::Log::EventFormatter
+    # @see Betterlog::Log::Severity
+    # @see Betterlog::GlobalMetadata
     class Event
-      require 'socket'
-
+      # Converts an input argument into a log event object with standardized
+      # formatting.
+      #
+      # This method processes various types of input including exceptions,
+      # strings, and hashes, transforming them into structured log events while
+      # preserving or enhancing their metadata. It ensures consistent event
+      # creation by normalizing keys and applying default values
+      # where necessary.
+      #
+      # @param arg [ Object ] the input argument to be converted into a log event
+      # @param rest [ Hash ] additional key-value pairs to be merged into the resulting event
+      # @return [ Betterlog::Log::Event ] a new log event instance created from the input argument
       def self.ify(arg, **rest)
         rest = rest.symbolize_keys_recursive(circular: :circular)
         if e = arg.ask_and_send(:exception)
@@ -23,11 +45,32 @@ module Betterlog
         end
       end
 
+      # Parses a JSON string into a new log event instance.
+      #
+      # This method takes a JSON representation of a log event and converts it
+      # into a structured event object. It attempts to parse the JSON string
+      # and create a new event using the parsed data. If the JSON is malformed
+      # or cannot be parsed, the method silently rescues the error and returns
+      # nil.
+      #
+      # @param json [ String ] a JSON-formatted string representing a log event
+      # @return [ Betterlog::Log::Event, nil ] a new log event instance if
+      # parsing succeeds, nil otherwise
       def self.parse(json)
         new(JSON.parse(json))
       rescue JSON::ParserError
       end
 
+      # Checks if a JSON string represents a log event with emitter data.
+      #
+      # This method attempts to parse a JSON string and determine whether it
+      # contains a log event structure by checking for the presence of an
+      # 'emitter' key in the parsed data. It returns true if the JSON is valid
+      # and contains the emitter key, false otherwise.
+      #
+      # @param json [ String ] A JSON-formatted string to check
+      # @return [ Boolean ] true if the JSON represents a log event with
+      # emitter data, false if not or if parsing fails
       def self.is?(json)
         if json = json.ask_and_send(:to_str)
           data = JSON.parse(json).ask_and_send(:to_hash)
@@ -37,6 +80,15 @@ module Betterlog
         false
       end
 
+      # Initializes a new log event with the provided data.
+      #
+      # This constructor processes the input data by normalizing keys, computing
+      # default values for missing fields, and setting up the event's severity level.
+      # It ensures that all log events have consistent structure and required fields
+      # such as timestamp, PID, program name, and host information.
+      #
+      # @param data [ Hash ] a hash containing the initial data for the log event
+      # @return [ Betterlog::Log::Event ] a new log event instance with processed data
       def initialize(data = {})
         data = compute_data(data.symbolize_keys_recursive(circular: :circular))
         data[:severity] =
@@ -51,10 +103,31 @@ module Betterlog
         @data = Hash[data.sort_by(&:first)]
       end
 
+      # Returns a duplicate of the internal data hash for JSON serialization.
+      #
+      # This method provides access to the log event's underlying data
+      # structure by returning a shallow copy of the internal @data instance
+      # variable. It is primarily used to enable JSON serialization of log
+      # events while ensuring that modifications to the returned hash do not
+      # affect the original event data.
+      #
+      # @return [ Hash ] a duplicate of the internal data hash containing all
+      #   log event attributes and metadata
       def as_json(*a)
         @data.dup
       end
 
+      # Converts the log event to a JSON string representation.
+      #
+      # This method generates a JSON-encoded string of the log event's data,
+      # providing a structured format suitable for logging and transmission.
+      # In cases where JSON generation fails due to encoding issues or other errors,
+      # it falls back to a minimal JSON representation containing only the severity
+      # and a cleaned-up message to ensure logging functionality remains intact.
+      #
+      # @return [ String ] A JSON string representation of the log event
+      # @see #as_json
+      # @see JSON.generate
       def to_json(*a)
         JSON.generate(as_json)
       rescue
@@ -67,44 +140,130 @@ module Betterlog
         })
       end
 
+      # Formats the log event using the specified formatting options.
+      #
+      # This method delegates to an EventFormatter instance to process the log
+      # event according to the provided arguments, enabling flexible output
+      # generation including JSON representation and pretty-printed strings
+      # with optional colorization.
+      #
+      # @param args [ Hash ] A hash of formatting options to control the output format
+      # @return [ String ] The formatted string representation of the log event
       def format(**args)
         Log::EventFormatter.new(self).format(**args)
       end
 
       alias to_s format
 
+      # Sets a value in the event data hash using the provided name as a key.
+      #
+      # This method allows for direct assignment of a value to a specific key
+      # within the log event's internal data structure. The key is converted to a
+      # symbol before being used to store the value, ensuring consistency with
+      # the internal storage format.
+      #
+      # @param name [ String, Symbol ] the key to set in the event data
+      # @param value [ Object ] the value to associate with the given key
+      # @return [ Object ] the assigned value
       def []=(name, value)
         @data[name.to_sym] = value
       end
 
+      # Retrieves a value from the event data hash using the provided name as a key.
+      #
+      # This method allows for access to specific fields stored within the log
+      # event's internal data structure by converting the provided name to a
+      # symbol and using it to look up the corresponding value.
+      #
+      # @param name [ String, Symbol ] the key used to retrieve the value from
+      # the event data
+      # @return [ Object, nil ] the value associated with the given key, or nil
+      # if the key does not exist
       def [](name)
         @data[name.to_sym]
       end
 
+      # Returns the severity level of the log event.
+      #
+      # This method provides access to the severity attribute that was assigned
+      # to the log event during its initialization. The severity indicates the
+      # importance or urgency of the log message, such as debug, info, warn,
+      # error, or fatal levels.
+      #
+      # @return [ Betterlog::Log::Severity ] the severity level object associated
+      #   with this log event
       def severity
         @data[:severity]
       end
 
+      # Returns the emitter identifier associated with the log event.
+      #
+      # This method provides access to the emitter field stored within the log
+      # event's data hash. The emitter typically indicates the source or type
+      # of system that generated the log entry, helping to categorize and route
+      # log messages appropriately.
+      #
+      # @return [ String, nil ] the emitter identifier if set, otherwise nil
       def emitter
         @data[:emitter]
       end
 
+      # Returns the notification flag from the log event data.
+      #
+      # This method retrieves the value associated with the :notify key from
+      # the event's internal data hash. The return value indicates whether the
+      # log event should trigger notifications to registered notifiers.
+      #
+      # @return [ Object, nil ] the notification setting from the event data,
+      # or nil if not set
       def notify?
         @data[:notify]
       end
 
+      # Checks equality between this log event and another object based on
+      # their internal data.
+      #
+      # This method compares the internal data hash of this log event with that
+      # of another object to determine if they contain identical content. It
+      # accesses the private @data instance variable from both objects and uses
+      # the built-in eql? method for hash comparison to ensure a deep equality
+      # check.
+      #
+      # @param other [ Object ] the object to compare against, expected to be another
+      #   Betterlog::Log::Event instance
+      # @return [ TrueClass, FalseClass ] true if both objects have equal internal data,
+      #   false otherwise
       def eql?(other)
         @data.eql? other.instance_variable_get(:@data)
       end
 
       alias == eql?
 
+      # Returns the hash value corresponding to the event's data.
+      #
+      # This method provides access to the cached hash representation of the
+      # internal data hash, which is used for consistent identification and
+      # comparison operations within the logging system. The returned hash
+      # value is derived from the event's current data state and remains stable
+      # as long as the data does not change.
+      #
+      # @return [ Integer ] the hash value of the event's internal data structure
       def hash
         @data.hash
       end
 
       private
 
+      # Processes input data to compute and enrich log event information.
+      #
+      # This method takes raw log data and enriches it with default values for
+      # standard log fields such as timestamp, process ID, program name, and
+      # host information. It also merges in global metadata and Sidekiq context
+      # information when available to provide comprehensive context for the log
+      # event.
+      #
+      # @param data [ Hash ] the raw input data to be processed and enriched
+      # @return [ Hash ] the processed data hash with default values and metadata merged in
       def compute_data(data)
         d = data | {
           timestamp: Time.now.utc.iso8601(3),

data/lib/betterlog/log/event_formatter.rb

@@ -3,14 +3,48 @@ require 'term/ansicolor'
 
 module Betterlog
   class Log
+    # Formats log events for structured logging output.
+    #
+    # This class provides functionality to format log events into various
+    # output formats, including JSON representation and pretty-printed strings
+    # with color support. It handles the conversion of log data into
+    # human-readable formats while maintaining structured logging capabilities.
+    #
+    # @see Betterlog::Log::Event
+    # @see Betterlog::Log::EventFormatter#format
     class EventFormatter
       include Term::ANSIColor
       include ComplexConfig::Provider::Shortcuts
 
+      # Initializes a new EventFormatter instance with the given log event.
+      #
+      # This constructor sets up the formatter with a specific log event to be
+      # formatted, preparing it for subsequent formatting operations such as
+      # JSON generation or pretty printing with color support.
+      #
+      # @param event [Betterlog::Log::Event] the log event to be formatted by
+      # this instance
+      # @return [Betterlog::Log::EventFormatter] a new EventFormatter instance
       def initialize(event)
         @event = event
       end
 
+      # Formats the log event according to specified options.
+      #
+      # This method processes a log event and returns either a JSON
+      # representation or a formatted string based on the provided formatting
+      # options. It supports pretty printing with custom format patterns and
+      # optional colorization.
+      #
+      # @param pretty [ Boolean, Symbol ] when true, enables pretty printing;
+      #   when :format, uses a specific format pattern; otherwise uses JSON generation
+      # @param color [ Boolean ] whether to apply color formatting to the output
+      # @param format [ Symbol ] the format identifier to use for pretty printing
+      #
+      # @return [ String ] the formatted log event as a string
+      #
+      # @see Betterlog::Log::EventFormatter#format_pattern
+      # @see JSON.generate
       def format(pretty: false, color: false, format: :default)
         old_coloring, Term::ANSIColor.coloring = Term::ANSIColor.coloring?, color
         f = cc.log.formats[format] and format = f
@@ -26,6 +60,20 @@ module Betterlog
 
       private
 
+      # Colorizes a string value based on configured styles for a given key and
+      # optional value.
+      #
+      # This method applies visual styling to a string by looking up the
+      # appropriate style configuration based on the provided key and value,
+      # then applying that style using the internal apply_style method.
+      #
+      # @param key [ Object ] the lookup key for determining the style
+      # configuration
+      # @param value [ Object ] the value used to determine which specific
+      # style to apply
+      # @param string [ Object ] the string to be colorized, defaults to the
+      # key if not provided
+      # @return [ String ] the colorized string based on the configured styles
       def colorize(key, value, string = key)
         case style = cc.log.styles[key]
         when nil, String, Array
@@ -35,6 +83,19 @@ module Betterlog
         end
       end
 
+      # Applies visual styling to a string using the provided style
+      # configuration.
+      #
+      # This method takes a style definition and applies it to a given string,
+      # supporting both single styles and arrays of styles. It handles the case
+      # where no style is provided by returning the string with reset
+      # formatting. When multiple styles are specified, they are applied
+      # sequentially to the string.
+      #
+      # @param style [ Object ] The style configuration to apply, which can be nil,
+      #   a string, an array of styles, or a ComplexConfig::Settings object
+      # @param string [ String ] The input string to which the style will be applied
+      # @return [ String ] The styled string with appropriate ANSI color codes inserted
       def apply_style(style, string)
         style.nil? and return string + Term::ANSIColor.reset
         string = Term::ANSIColor.uncolor(string)
@@ -48,6 +109,18 @@ module Betterlog
         end
       end
 
+      # Formats a log event using a specified pattern with support for
+      # directives and colorization.
+      #
+      # This method processes a format string by replacing placeholders with
+      # actual event data, applying formatting directives for special handling
+      # of values like objects or timestamps, and optionally applying color
+      # styling based on configured styles.
+      #
+      # @param format [ String ] the format pattern to apply to the log event
+      # @return [ String ] the formatted string representation of the log event
+      # @see Betterlog::Log::EventFormatter#format_object
+      # @see Betterlog::Log::EventFormatter#colorize
       def format_pattern(format:)
         format.
           gsub('\n', "\n").
@@ -99,6 +172,23 @@ module Betterlog
           }
       end
 
+      # Formats complex objects into a readable string representation with
+      # nested structure visualization.
+      #
+      # This method recursively processes arrays and hashes, converting them
+      # into indented string representations that show the hierarchical
+      # structure of the data. It handles nested arrays and hashes by
+      # increasing the indentation level for each nesting level, making it
+      # easier to visualize the data structure.
+      #
+      # @param object [ Object ] the object to be formatted, which can be an
+      # array, hash, or any other object
+      # @param depth [ Integer ] the current depth level for indentation, used
+      # internally during recursion
+      # @param nl [ String ] the newline character or string to use for
+      # separating elements
+      # @return [ String ] a formatted string representation of the object,
+      # with proper indentation for nested structures
       def format_object(object, depth: 0, nl: ?\n)
         case
         when a = object.ask_and_send(:to_ary)

data/lib/betterlog/log/legacy_event_formatter.rb

@@ -2,14 +2,44 @@ require 'term/ansicolor'
 
 module Betterlog
   class Log
+    # Formats log messages for legacy Rails logging compatibility.
+    #
+    # This class provides a formatter that integrates with Rails' legacy
+    # logging system, converting standard log messages into structured JSON
+    # events while preserving the original formatting behavior for backward
+    # compatibility.
+    #
+    # @see Betterlog::Log::Event
+    # @see ActiveSupport::Logger::Formatter
     class LegacyEventFormatter < ::ActiveSupport::Logger::Formatter
       include ActiveSupport::TaggedLogging::Formatter
       include ComplexConfig::Provider::Shortcuts
 
+      # Returns the emitter identifier string for legacy log events.
+      #
+      # This method provides a constant string value that represents the
+      # emitter type for logs formatted using the legacy event formatter.
+      #
+      # @return [ String ] the string 'legacy' indicating the legacy emitter type
       def emitter
         'legacy'
       end
 
+      # Processes a log message using the legacy formatting approach.
+      #
+      # This method handles the conversion of standard log messages into
+      # structured JSON events when legacy logging support is enabled. It
+      # extracts relevant information from the input message, such as
+      # backtraces and location data, and formats it according to the legacy
+      # event structure.
+      #
+      # @param severity [ String ] the severity level of the log message
+      # @param timestamp [ Time ] the time when the log entry was created
+      # @param program [ String ] the name of the program generating the log
+      # @param message [ String ] the raw log message content
+      #
+      # @return [ String ] the formatted log message, either as a JSON event or
+      #   the original message if it's not suitable for conversion
       def call(severity, timestamp, program, message)
         if cc.log.legacy_supported
           if message.blank?

data/lib/betterlog/log/severity.rb

@@ -2,13 +2,42 @@ require 'logger'
 
 module Betterlog
   class Log
+    # A severity level representation for logging events.
+    #
+    # This class provides a structured way to handle logging severity levels,
+    # ensuring consistent formatting and comparison of severity values. It
+    # integrates with Ruby's standard Logger::Severity constants while
+    # providing additional functionality for normalization, caching, and
+    # comparison operations.
+    #
+    # @see Betterlog::Log::Event
+    # @see Logger::Severity
     class Severity
       include ::Logger::Severity
       include Comparable
 
       class << self
+
+        # Defines a thread-local variable named shared within the class.
+        #
+        # This method sets up a thread-local storage area called shared,
+        # which can be used to store data that is unique to each thread.
+        # It is typically used to maintain state or caches that should
+        # not be shared across different threads in a multi-threaded environment.
         thread_local :shared
 
+        # Creates a new Severity instance with the given name, normalizing it
+        # to uppercase symbols for consistent lookup.
+        #
+        # This method converts the input name to a standardized format by
+        # converting it to a symbol, uppercasing its string representation, and
+        # then attempting to retrieve or create a corresponding Severity
+        # constant. It ensures that only one instance exists per unique
+        # severity name by using a shared cache.
+        #
+        # @param name [ String, Symbol, Betterlog::Log::Severity ] the severity
+        # name to initialize with
+        # @return [ Betterlog::Log::Severity ] a new or cached severity instance
         def new(name)
           name = name.to_sym if self.class === name
           name = name.to_s.upcase.to_sym
@@ -17,6 +46,17 @@ module Betterlog
         end
       end
 
+      # Initializes a new Severity instance with the given name.
+      #
+      # This constructor creates a severity level object by converting the
+      # input name to a standardized symbol format and attempting to map it to
+      # a corresponding logger severity constant. If the constant is not found,
+      # it defaults to the UNKNOWN severity level.
+      #
+      # @param name [ String, Symbol, Betterlog::Log::Severity ] the severity name
+      #   to initialize with, which will be converted to uppercase and normalized
+      #   to a symbol for lookup
+      # @return [ Betterlog::Log::Severity ] a new severity instance
       def initialize(name)
         name = name.to_sym if self.class === name
         @name = name.to_s.downcase.to_sym
@@ -28,36 +68,100 @@ module Betterlog
         end
       end
 
+      # Returns an array of all Severity constants as initialized objects.
+      #
+      # This method retrieves all available severity constants defined in the
+      # class and creates a new instance of Severity for each one. The results
+      # are cached in an instance variable to avoid re-computation on
+      # subsequent calls.
+      #
+      # @return [ Array<Betterlog::Log::Severity> ] an array containing Severity
+      #   instances for each constant defined in the class
       def self.all
         @all_constants ||= constants.map { |c| new(c) }
       end
 
+      # Converts the severity level to its integer representation.
+      #
+      # This method returns the underlying integer value that represents the
+      # severity level, which corresponds to standard logging severity
+      # constants.
+      #
+      # @return [ Integer ] the integer value of the severity level
       def to_i
         @level
       end
 
+      # Converts the severity name to an uppercase string representation.
+      #
+      # This method returns a string version of the severity name, converted to
+      # uppercase for consistent formatting and display purposes.
+      #
+      # @return [ String ] the uppercase string representation of the severity name
       def to_s
         @name.to_s.upcase
       end
 
+      # Converts the severity name to a symbol representation.
+      #
+      # This method returns the internal symbol representation of the severity
+      # name, which is used for consistent identification and comparison of
+      # severity levels.
+      #
+      # @return [ Symbol ] the symbol representation of the severity name
       def to_sym
         @name
       end
 
+      # Converts the log event to a JSON-compatible hash representation.
+      #
+      # This method provides a way to serialize the log event data into a
+      # format suitable for JSON generation, ensuring that the event's data can
+      # be easily converted to a JSON string while maintaining its structure
+      # and content.
+      #
+      # @return [ Hash ] a hash representation of the log event data
       def as_json(*)
         to_s
       end
 
+      # Compares this severity instance with another value for ordering.
+      #
+      # This method enables sorting and comparison of severity levels by
+      # converting both the current instance and the provided value to their
+      # integer representations and performing a standard numeric comparison.
+      #
+      # @param other [ Object ] the value to compare against, which will be converted
+      #   to a Severity instance for comparison
+      # @return [ Integer ] -1 if this instance is less than the other, 0 if they are
+      #   equal, 1 if this instance is greater than the other
       def <=>(other)
         to_i <=> self.class.new(other).to_i
       end
 
+      # Checks equality between this severity instance and another object based
+      # on their symbol representations.
+      #
+      # This method compares the symbol representation of the current severity
+      # instance with that of another object to determine if they are
+      # equivalent.
+      #
+      # @param other [ Object ] the object to compare against
+      # @return [ TrueClass, FalseClass ] true if both objects have equal
+      # symbol representations, false otherwise
       def eql?(other)
         to_sym == other.to_sym
       end
 
       alias == eql?
 
+      # Returns the hash value corresponding to the severity name symbol.
+      #
+      # This method provides a hash representation of the internal symbol
+      # identifier for the severity level, which is used for consistent
+      # identification and comparison operations within the logging system.
+      #
+      # @return [ Integer ] the hash value of the severity name symbol
       def hash
         @name.hash
       end