betterlog 2.0.5 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec46f272cea0612996e80343c2aee7c470db5329876cce825001b14af8d3feea
-  data.tar.gz: 45396c9c4c3f2396820e107b11a51c294b0d8461181b6b0230573513ee957894
+  metadata.gz: e5b1ea80565dc5b5e0b95a525f8e50a3aded59cd3038c2e76610d6fe36427d20
+  data.tar.gz: 8b98f5b839d2bbaecb6bd2171a52e11c728a00eb415039d833669016b842fc2a
 SHA512:
-  metadata.gz: 79243eea8ef0928a0aff2713051d86fe877505d82685ece7f55057341391bcb95565fb0def39b98e1045e1a190a9a731349de765a025e28e981c847d3599bc5b
-  data.tar.gz: 138c8aa6bf6858d0ba208dd8e14f2e3901f16a65f2e53fc336c649bf313df6d57e9a6a369a31f8661fd2754d5c1ace055cd9ef7a4460dc0a9a62e305c811a217
+  metadata.gz: 5d9306aa22d8b0032d684d0e61026059aed39bf19ea2f83cef327d60b982f534eb70740e59e6610cc38223980cbab152ee9942e7c3b6af02418d1cec4bbc6182
+  data.tar.gz: 372ab8b900747df79f51019b6905a66065b3c00157484da3aa3a5c963517e61411b2da7e443ae900d34af842d2d4f7fecccf09827b03adc947a9d57e5589a9af

data/.tool-versions

@@ -1 +1 @@
-ruby 3.4.1
+ruby 3.4.5

data/Rakefile

@@ -17,6 +17,7 @@ GemHadar do
   readme      'README.md'
   title       "#{name.camelize}"
   executables %w[ betterlog ]
+  licenses    << 'Apache-2.0'
 
   dependency 'tins',           '~>1.3', '>=1.22.0'
   dependency 'complex_config'

data/VERSION

@@ -1 +1 @@
-2.0.5
+2.1.0

data/betterlog.gemspec

@@ -1,28 +1,29 @@
 # -*- encoding: utf-8 -*-
-# stub: betterlog 2.0.5 ruby lib
+# stub: betterlog 2.1.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "betterlog".freeze
-  s.version = "2.0.5".freeze
+  s.version = "2.1.0".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
   s.authors = ["betterplace Developers".freeze]
-  s.date = "2025-02-13"
+  s.date = "1980-01-02"
   s.description = "This library provides structure json logging for our rails projects".freeze
   s.email = "developers@betterplace.org".freeze
   s.executables = ["betterlog".freeze]
   s.extra_rdoc_files = ["README.md".freeze, "lib/betterlog.rb".freeze, "lib/betterlog/global_metadata.rb".freeze, "lib/betterlog/log.rb".freeze, "lib/betterlog/log/event.rb".freeze, "lib/betterlog/log/event_formatter.rb".freeze, "lib/betterlog/log/legacy_event_formatter.rb".freeze, "lib/betterlog/log/severity.rb".freeze, "lib/betterlog/notifiers.rb".freeze, "lib/betterlog/railtie.rb".freeze, "lib/betterlog/version.rb".freeze]
   s.files = [".all_images.yml".freeze, ".github/workflows/codeql-analysis.yml".freeze, ".gitignore".freeze, ".semaphore/semaphore.yml".freeze, ".tool-versions".freeze, "Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "Rakefile".freeze, "VERSION".freeze, "betterlog.gemspec".freeze, "bin/betterlog".freeze, "config/log.yml".freeze, "lib/betterlog.rb".freeze, "lib/betterlog/global_metadata.rb".freeze, "lib/betterlog/log.rb".freeze, "lib/betterlog/log/event.rb".freeze, "lib/betterlog/log/event_formatter.rb".freeze, "lib/betterlog/log/legacy_event_formatter.rb".freeze, "lib/betterlog/log/severity.rb".freeze, "lib/betterlog/notifiers.rb".freeze, "lib/betterlog/railtie.rb".freeze, "lib/betterlog/version.rb".freeze, "spec/betterlog/global_metadata_spec.rb".freeze, "spec/betterlog/log/event_spec.rb".freeze, "spec/betterlog/log/legacy_event_formatter_spec.rb".freeze, "spec/betterlog/log/severity_spec.rb".freeze, "spec/betterlog/log_spec.rb".freeze, "spec/betterlog/version_spec.rb".freeze, "spec/spec_helper.rb".freeze]
   s.homepage = "http://github.com/betterplace/betterlog".freeze
+  s.licenses = ["Apache-2.0".freeze]
   s.rdoc_options = ["--title".freeze, "Betterlog".freeze, "--main".freeze, "README.md".freeze]
-  s.rubygems_version = "3.6.2".freeze
+  s.rubygems_version = "3.6.9".freeze
   s.summary = "Structured logging support for bp".freeze
   s.test_files = ["spec/betterlog/global_metadata_spec.rb".freeze, "spec/betterlog/log/event_spec.rb".freeze, "spec/betterlog/log/legacy_event_formatter_spec.rb".freeze, "spec/betterlog/log/severity_spec.rb".freeze, "spec/betterlog/log_spec.rb".freeze, "spec/betterlog/version_spec.rb".freeze, "spec/spec_helper.rb".freeze]
 
   s.specification_version = 4
 
-  s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 1.19".freeze])
+  s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 1.28".freeze])
   s.add_development_dependency(%q<rake>.freeze, [">= 0".freeze])
   s.add_development_dependency(%q<rspec>.freeze, [">= 0".freeze])
   s.add_development_dependency(%q<simplecov>.freeze, [">= 0".freeze])

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

data/lib/betterlog/log.rb

@@ -5,6 +5,16 @@ require 'betterlog/log/event_formatter'
 require 'betterlog/log/severity'
 
 module Betterlog
+  # A flexible, framework-agnostic logging solution that provides a clean API
+  # for structured logging with automatic Rails integration and error recovery.
+  #
+  # This class implements a singleton pattern using Tins::SexySingleton and
+  # automatically detects Rails environment to use its logger when available.
+  # It supports structured logging with contextual information, location
+  # tracking, and event notification capabilities.
+  #
+  # @example Basic usage
+  #   Betterlog::Log.info("User logged in", meta: { user_id: 123 })
   class Log
     include Tins::SexySingleton
     extend ComplexConfig::Provider::Shortcuts
@@ -15,6 +25,12 @@ module Betterlog
       default_logger.level = level
     end
 
+    # Returns the appropriate logger instance for the application.
+    #
+    # This method checks if Rails is defined and has a logger available,
+    # falling back to a default logger otherwise.
+    #
+    # @return [Logger] The Rails logger if available, otherwise the default logger.
     def logger
       defined?(Rails) && Rails.respond_to?(:logger) ? Rails.logger : self.class.default_logger
     end
@@ -22,7 +38,7 @@ module Betterlog
     # Logs a message on severity info.
     #
     # @param object this object is logged
-    # @param **rest additional data is logged as well.
+    # @param rest additional data is logged as well.
     # @return [ Log ] this object itself.
     def info(object, **rest)
       protect do
@@ -34,7 +50,7 @@ module Betterlog
     # Logs a message on severity warn.
     #
     # @param object this object is logged
-    # @param **rest additional data is logged as well.
+    # @param rest additional data is logged as well.
     # @return [ Log ] this object itself.
     def warn(object, **rest)
       protect do
@@ -46,7 +62,7 @@ module Betterlog
     # Logs a message on severity debug.
     #
     # @param object this object is logged
-    # @param **rest additional data is logged as well.
+    # @param rest additional data is logged as well.
     # @return [ Log ] this object itself.
     def debug(object, **rest)
       protect do
@@ -58,7 +74,7 @@ module Betterlog
     # Logs a message on severity error.
     #
     # @param object this object is logged
-    # @param **rest additional data is logged as well.
+    # @param rest additional data is logged as well.
     # @return [ Log ] this object itself.
     def error(object, **rest)
       protect do
@@ -70,7 +86,7 @@ module Betterlog
     # Logs a message on severity fatal.
     #
     # @param object this object is logged
-    # @param **rest additional data is logged as well.
+    # @param rest additional data is logged as well.
     # @return [ Log ] this object itself.
     def fatal(object, **rest)
       protect do
@@ -83,7 +99,7 @@ module Betterlog
     # passing the severity: keyword.
     #
     # @param object this object is logged
-    # @param **rest additional data is logged as well.
+    # @param rest additional data is logged as well.
     # @return [ Log ] this object itself.
     def output(object, **rest)
       protect do
@@ -91,10 +107,16 @@ module Betterlog
       end
     end
 
-    def metric(name:, value: nil, success: -> result { true }, **rest, &block)
-      warn "#{self.class}##{__method__} is deprecated"
-    end
-
+    # Emits a log event by adding contextual information, notifying
+    # subscribers, and logging through the configured logger.
+    #
+    # This method enhances the provided event with location information if
+    # available, sets the emitter identifier, triggers any registered
+    # notifiers, and finally logs the event using the application's logger at
+    # the event's severity level.
+    #
+    # @param event [Betterlog::Log::Event] the log event to be emitted
+    # @return [Betterlog::Log] the log instance itself
     def emit(event)
       l = caller_locations.reverse_each.each_cons(3).find { |c, n1, n2|
         n2.absolute_path =~ /betterlog\/log\.rb/ and break c # TODO check if this still works

data/lib/betterlog/notifiers.rb

@@ -1,10 +1,31 @@
 module Betterlog
+  # Module for managing and coordinating log event notifiers.
+  #
+  # This module provides a centralized mechanism for registering and notifying
+  # objects when specific log events occur. It maintains a collection of
+  # notifier instances that can respond to log events, allowing for flexible
+  # integration with external monitoring, alerting, or logging systems.
+  # Notifiers are invoked when log events explicitly request notification,
+  # enabling decoupled communication between the logging system and downstream
+  # services.
+  #
+  # @see Betterlog::Log#emit
+  # @see Betterlog::Log::Event#notify?
   module Notifiers
 
     class_attr_accessor :notifiers
 
     self.notifiers = Set[]
 
+    # Registers a notifier object with the Notifiers module.
+    #
+    # This method adds a notifier to the collection of registered notifiers,
+    # ensuring that it responds to the required notify interface. The notifier
+    # will subsequently be invoked when log events with notification requests
+    # are emitted.
+    #
+    # @param notifier [ Object ] the notifier object to be registered
+    # @return [ Class ] Returns the Notifiers class itself
     def self.register(notifier)
       notifier.respond_to?(:notify) or raise TypeError,
         "notifier has to respond to notify(message, hash) interface"
@@ -12,6 +33,14 @@ module Betterlog
       self
     end
 
+    # Notifies registered notifiers with the event data.
+    #
+    # This method checks if the provided event has notification enabled,
+    # and if so, iterates through all registered notifiers to send them
+    # the event's message and metadata. It also updates the context for
+    # each notifier before sending the notification.
+    #
+    # @param event [Betterlog::Log::Event] the log event to be notified about
     def self.notify(event)
       event.notify? or return
       notifiers.each do |notifier|
@@ -20,6 +49,15 @@ module Betterlog
       end
     end
 
+    # Sets the context for all registered notifiers with the provided data.
+    #
+    # This method iterates through all registered notifiers and invokes their
+    # context method if they respond to it, passing the given data hash to
+    # allow notifiers to update their internal state or configuration based
+    # on the provided context information.
+    #
+    # @param data [ Hash ] A hash containing the context data to be passed
+    #   to each notifier that supports the context interface
     def self.context(data)
       notifiers.each do |notifier|
         notifier.respond_to?(:context) or next

data/lib/betterlog/railtie.rb

@@ -1,4 +1,12 @@
 module Betterlog
+  # Integrates Betterlog with Rails application initialization.
+  #
+  # This Railtie is responsible for configuring Rails to use Betterlog's legacy event formatter
+  # as the default logger formatter. It ensures that log messages are properly structured
+  # and enriched with metadata when used within a Rails application context.
+  #
+  # @see Betterlog::Log::LegacyEventFormatter
+  # @see Rails::Railtie
   class Railtie < Rails::Railtie
     initializer "betterlog_railtie.configure_rails_initialization" do
       require 'betterlog/log/legacy_event_formatter'

data/lib/betterlog/version.rb

@@ -1,6 +1,6 @@
 module Betterlog
   # Betterlog version
-  VERSION         = '2.0.5'
+  VERSION         = '2.1.0'
   VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

data/lib/betterlog.rb

@@ -3,6 +3,12 @@ require 'json'
 require 'complex_config'
 require 'term/ansicolor'
 
+# Main module for Betterlog logging functionality.
+#
+# Provides structured logging tools designed for betterplace's logging
+# infrastructure in Rails applications. Offers thread-local metadata
+# management, event formatting, severity handling, and integration with Rails
+# logging systems.
 module Betterlog
 end
 
@@ -16,3 +22,12 @@ if defined? Rails
 end
 
 Log = Betterlog::Log
+
+# This class serves as a convenience alias for the Betterlog::Log module,
+# providing a simple way to access the logging functionality throughout a Rails
+# application
+#
+# @see Betterlog::Log
+# @see Betterlog
+class Log
+end

data/spec/spec_helper.rb

@@ -1,9 +1,5 @@
-if ENV['START_SIMPLECOV'].to_i == 1
-  require 'simplecov'
-  SimpleCov.start do
-    add_filter "#{File.basename(File.dirname(__FILE__))}/"
-  end
-end
+require 'gem_hadar/simplecov'
+GemHadar::SimpleCov.start
 require 'rspec'
 begin
   require 'debug'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: betterlog
 version: !ruby/object:Gem::Version
-  version: 2.0.5
+  version: 2.1.0
 platform: ruby
 authors:
 - betterplace Developers
 bindir: bin
 cert_chain: []
-date: 2025-02-13 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: gem_hadar
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.19'
+        version: '1.28'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.19'
+        version: '1.28'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -246,7 +246,8 @@ files:
 - spec/betterlog/version_spec.rb
 - spec/spec_helper.rb
 homepage: http://github.com/betterplace/betterlog
-licenses: []
+licenses:
+- Apache-2.0
 metadata: {}
 rdoc_options:
 - "--title"
@@ -266,7 +267,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Structured logging support for bp
 test_files: