lumberjack 1.4.2 → 2.0.0

data/lib/lumberjack/message_attributes.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Lumberjack
+  # This class can be used as the return value from a formatter +call+ method to
+  # extract additional attributes from an object being logged. This can be useful when there
+  # using structured logging to include important metadata in the log entry in addition
+  # to the message.
+  #
+  # @example
+  #  # Automatically add attributes with error details when logging an exception.
+  #  logger.add_formatter(Exception, ->(e) {
+  #    Lumberjack::MessageAttributes.new(e.inspect, {
+  #      error: {
+  #        message: e.message,
+  #        class: e.class.name,
+  #        stack: e.backtrace
+  #      }
+  #    })
+  #  })
+  class MessageAttributes
+    attr_reader :message, :attributes
+
+    # @param message [Object] The message to be logged.
+    # @param attributes [Hash] The attributes to be associated with the message.
+    def initialize(message, attributes)
+      @message = message
+      @attributes = attributes || {}
+    end
+
+    def to_s
+      inspect
+    end
+
+    def inspect
+      {message: @message, attributes: @attributes}.inspect
+    end
+  end
+end

data/lib/lumberjack/rack/context.rb

@@ -2,35 +2,86 @@
 
 module Lumberjack
   module Rack
-    # Middleware to create a global context for Lumberjack for the scope of a rack request.
+    # Rack middleware ensures that a global Lumberjack context exists for
+    # the duration of each HTTP request. This middleware creates an isolated
+    # logging context that automatically cleans up after the request completes,
+    # ensuring that request-specific attributes don't leak between requests.
     #
-    # The optional `env_tags` parameter can be used to set up global tags from the request
-    # environment. This is useful for setting tags that are relevant to the entire request
-    # like the request id, host, etc.
+    # The middleware supports dynamic attribute extraction from the Rack environment,
+    # allowing automatic tagging of log entries with request-specific information
+    # such as request IDs, user agents, IP addresses, or any other data available
+    # in the Rack environment.
+    #
+    # This is particularly useful in web applications where you want to correlate
+    # all log entries within a single request with common identifying information,
+    # making it easier to trace request flows and debug issues.
+    #
+    # @example Basic usage in a Rack application
+    #   use Lumberjack::Rack::Context
+    #
+    # @example With static attributes
+    #   use Lumberjack::Rack::Context, {
+    #     app_name: "MyWebApp",
+    #     version: "1.2.3"
+    #   }
+    #
+    # @example With dynamic attributes from request environment
+    #   use Lumberjack::Rack::Context, {
+    #     request_id: ->(env) { env["HTTP_X_REQUEST_ID"] },
+    #     user_agent: ->(env) { env["HTTP_USER_AGENT"] },
+    #     remote_ip: ->(env) { env["REMOTE_ADDR"] },
+    #     method: ->(env) { env["REQUEST_METHOD"] },
+    #     path: ->(env) { env["PATH_INFO"] }
+    #   }
+    #
+    # @example Rails integration
+    #   # In config/application.rb
+    #   config.middleware.use Lumberjack::Rack::Context, {
+    #     request_id: ->(env) { env["action_dispatch.request_id"] },
+    #     session_id: ->(env) { env["rack.session"]&.id },
+    #     user_id: ->(env) { env["warden"]&.user&.id }
+    #   }
+    #
+    # @see Lumberjack.context
+    # @see Lumberjack.tag
     class Context
-      # @param [Object] app The rack application.
-      # @param [Hash] env_tags A hash of tags to set from the request environment. If a tag value is
-      #   a Proc, it will be called with the request `env` as an argument to allow dynamic tag values
-      #   based on request data.
-      def initialize(app, env_tags = nil)
+      # Initialize the middleware with the Rack application and optional environment
+      # attribute configuration. The middleware will create a scoped logging context
+      # for each request and automatically apply the specified attributes.
+      #
+      # @param app [Object] The next Rack application in the middleware stack
+      # @param env_attributes [Hash, nil] Optional hash defining attributes to extract
+      #   from the request environment. Values can be:
+      #   - Static values: Applied directly to all requests
+      #   - Proc objects: Called with the Rack env hash to generate dynamic values
+      #   - Any callable: Invoked with env to produce request-specific attributes
+      def initialize(app, env_attributes = nil)
         @app = app
-        @env_tags = env_tags
+        @env_attributes = env_attributes
       end
 
+      # Process a Rack request within a scoped Lumberjack logging context.
+      #
+      # @param env [Hash] The Rack environment hash containing request information
+      # @return [Array] The standard Rack response array [status, headers, body]
       def call(env)
-        Lumberjack.context do
-          apply_tags(env) if @env_tags
+        Lumberjack.ensure_context do
+          apply_attributes(env) if @env_attributes
           @app.call(env)
         end
       end
 
       private
 
-      def apply_tags(env)
-        tags = @env_tags.transform_values do |value|
+      # Apply configured environment attributes to the current logging context.
+      #
+      # @param env [Hash] The Rack environment hash
+      # @return [void]
+      def apply_attributes(env)
+        attributes = @env_attributes.transform_values do |value|
           value.is_a?(Proc) ? value.call(env) : value
         end
-        Lumberjack.tag(tags)
+        Lumberjack.tag(attributes)
       end
     end
   end

data/lib/lumberjack/rack.rb

@@ -2,8 +2,6 @@
 
 module Lumberjack
   module Rack
-    require_relative "rack/unit_of_work"
-    require_relative "rack/request_id"
     require_relative "rack/context"
   end
 end

data/lib/lumberjack/remap_attribute.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Lumberjack
+  # This class can be used as a return value from an AttributeFormatter to indicate that the
+  # value should be remapped to a new attribute name.
+  #
+  # @example
+  #   # Transform duration_millis and duration_micros to seconds and move to
+  #   # the duration attribute.
+  #   logger.formatter.format_attribute_name("duration_ms") do |value|
+  #     Lumberjack::RemapAttribute.new("duration" => value.to_f / 1000)
+  #   end
+  #   logger.formatter.format_attribute_name("duration_micros") do |value|
+  #     Lumberjack::RemapAttribute.new("duration" => value.to_f / 1_000_000)
+  #   end
+  class RemapAttribute
+    attr_reader :attributes
+
+    # @param remapped_attributes [Hash] The remapped attribute with the new names.
+    def initialize(remapped_attributes)
+      @attributes = Lumberjack::Utils.flatten_attributes(remapped_attributes)
+    end
+  end
+end

data/lib/lumberjack/severity.rb

@@ -3,44 +3,81 @@
 module Lumberjack
   # The standard severity levels for logging messages.
   module Severity
-    # Backward compatibilty with 1.0 API
-    DEBUG = ::Logger::Severity::DEBUG
-    INFO = ::Logger::Severity::INFO
-    WARN = ::Logger::Severity::WARN
-    ERROR = ::Logger::Severity::ERROR
-    FATAL = ::Logger::Severity::FATAL
-    UNKNOWN = ::Logger::Severity::UNKNOWN
+    # Custom severity level for trace messages, lower than DEBUG.
+    TRACE = -1
 
-    SEVERITY_LABELS = %w[DEBUG INFO WARN ERROR FATAL UNKNOWN].freeze
+    DEBUG = Logger::Severity::DEBUG
+    INFO = Logger::Severity::INFO
+    WARN = Logger::Severity::WARN
+    ERROR = Logger::Severity::ERROR
+    FATAL = Logger::Severity::FATAL
+    UNKNOWN = Logger::Severity::UNKNOWN
+
+    SEVERITY_LABELS = %w[TRACE DEBUG INFO WARN ERROR FATAL ANY].freeze
+    private_constant :SEVERITY_LABELS
+
+    # Data object for severity levels that includes variations on the label.
+    class Data
+      attr_reader :level, :label, :padded_label, :char, :emoji, :terminal_color
+
+      def initialize(level, label, emoji, terminal_color)
+        @level = level
+        @label = label.freeze
+        @padded_label = label.ljust(5).freeze
+        @char = label[0].freeze
+        @emoji = emoji.freeze
+        @terminal_color = "\e[38;5;#{terminal_color}m"
+      end
+    end
+
+    SEVERITIES = [
+      Data.new(TRACE, "TRACE", "🔍", 247).freeze,
+      Data.new(DEBUG, "DEBUG", "🔧", 244).freeze,
+      Data.new(INFO, "INFO", "🔵", 33).freeze,
+      Data.new(WARN, "WARN", "🟡", 208).freeze,
+      Data.new(ERROR, "ERROR", "❌", 9).freeze,
+      Data.new(FATAL, "FATAL", "🔥", 160).freeze,
+      Data.new(UNKNOWN, "ANY", "❓", 129).freeze
+    ].freeze
+    private_constant :SEVERITIES
 
     class << self
       # Convert a severity level to a label.
       #
-      # @param [Integer] severity The severity level to convert.
+      # @param severity [Integer] The severity level to convert.
       # @return [String] The severity label.
       def level_to_label(severity)
-        SEVERITY_LABELS[severity] || SEVERITY_LABELS.last
+        SEVERITIES[severity + 1]&.label || SEVERITIES.last.label
       end
 
       # Convert a severity label to a level.
       #
-      # @param [String, Symbol] label The severity label to convert.
+      # @param label [String, Symbol] The severity label to convert.
       # @return [Integer] The severity level.
       def label_to_level(label)
-        SEVERITY_LABELS.index(label.to_s.upcase) || UNKNOWN
+        label = label.to_s.upcase
+        (SEVERITY_LABELS.index(label) || UNKNOWN + 1) - 1
       end
 
       # Coerce a value to a severity level.
       #
-      # @param [Integer, String, Symbol] value The value to coerce.
+      # @param value [Integer, String, Symbol] The value to coerce.
       # @return [Integer] The severity level.
       def coerce(value)
-        if value.is_a?(Integer)
-          value
+        if value.is_a?(Numeric)
+          value.to_i
         else
           label_to_level(value)
         end
       end
+
+      # Return a data object that maps the severity level to variations on the label.
+      #
+      # @param level [Integer, String, Symbol] The severity level.
+      # @return [SeverityData] The severity data object.
+      def data(level)
+        SEVERITIES[coerce(level) + 1] || SEVERITIES.last
+      end
     end
   end
 end

data/lib/lumberjack/tag_context.rb

@@ -1,78 +1,15 @@
 # frozen_string_literal: true
 
 module Lumberjack
-  # A tag context provides an interface for manipulating a tag hash.
-  class TagContext
-    def initialize(tags)
-      @tags = tags
-    end
-
-    # Merge new tags into the context tags. Tag values will be flattened using dot notation
-    # on the keys. So `{ a: { b: 'c' } }` will become `{ 'a.b' => 'c' }`.
-    #
-    # If a block is given, then the tags will only be added for the duration of the block.
-    #
-    # @param tags [Hash] The tags to set.
-    # @return [void]
-    def tag(tags)
-      @tags.merge!(Utils.flatten_tags(tags))
-    end
-
-    # Get a tag value.
-    #
-    # @param name [String, Symbol] The tag key.
-    # @return [Object] The tag value.
-    def [](name)
-      return nil if @tags.empty?
-
-      name = name.to_s
-      return @tags[name] if @tags.include?(name)
-
-      # Check for partial matches in dot notation and return the hash representing the partial match.
-      prefix_key = "#{name}."
-      matching_tags = {}
-      @tags.each do |key, value|
-        if key.start_with?(prefix_key)
-          # Remove the prefix to get the relative key
-          relative_key = key[prefix_key.length..-1]
-          matching_tags[relative_key] = value
-        end
+  # This class was renamed to Lumberjack::AttributesHelper. This class is provided for
+  # backward compatibility with the version 1.x API and will eventually be removed.
+  #
+  # @deprecated Use Lumberjack::AttributesHelper instead.
+  class TagContext < AttributesHelper
+    def initialize
+      Utils.deprecated("Lumberjack::TagContext", "Use Lumberjack::AttributesHelper instead.") do
+        super
       end
-
-      return nil if matching_tags.empty?
-      matching_tags
-    end
-
-    # Set a tag value.
-    #
-    # @param name [String, Symbol] The tag name.
-    # @param value [Object] The tag value.
-    # @return [void]
-    def []=(name, value)
-      if value.is_a?(Hash)
-        @tags.merge!(Utils.flatten_tags(name => value))
-      else
-        @tags[name.to_s] = value
-      end
-    end
-
-    # Remove tags from the context.
-    #
-    # @param names [Array<String, Symbol>] The tag names to remove.
-    # @return [void]
-    def delete(*names)
-      names.each do |name|
-        prefix_key = "#{name}."
-        @tags.delete_if { |k, _| k == name.to_s || k.start_with?(prefix_key) }
-      end
-      nil
-    end
-
-    # Return a copy of the tags as a hash.
-    #
-    # @return [Hash]
-    def to_h
-      @tags.dup
     end
   end
 end

data/lib/lumberjack/tag_formatter.rb

@@ -1,197 +1,31 @@
 # frozen_string_literal: true
 
 module Lumberjack
-  # Class for formatting tags. You can register a default formatter and tag
-  # name specific formatters. Formatters can be either `Lumberjack::Formatter`
-  # objects or any object that responds to `call`.
+  # TagFormatter has been renamed to {AttributeFormatter} as part of the transition from
+  # "tags" to "attributes" terminology in Lumberjack 2.0. This class exists solely for
+  # backward compatibility with the 1.x API and will be removed in a future version.
   #
-  # tag_formatter = Lumberjack::TagFormatter.new.default(Lumberjack::Formatter.new)
-  # tag_formatter.add(["password", "email"]) { |value| "***" }
-  # tag_formatter.add("finished_at", Lumberjack::Formatter::DateTimeFormatter.new("%Y-%m-%dT%H:%m:%S%z"))
-  class TagFormatter
-    def initialize
-      @formatters = {}
-      @class_formatters = {}
-      @default_formatter = nil
-    end
-
-    # Add a default formatter applied to all tag values. This can either be a Lumberjack::Formatter
-    # or an object that responds to `call` or a block.
-    #
-    # @param formatter [Lumberjack::Formatter, #call, nil] The formatter to use.
-    #    If this is nil, then the block will be used as the formatter.
-    # @return [Lumberjack::TagFormatter] self
-    def default(formatter = nil, &block)
-      formatter ||= block
-      formatter = dereference_formatter(formatter)
-      @default_formatter = formatter
-      self
-    end
-
-    # Remove the default formatter.
-    #
-    # @return [Lumberjack::TagFormatter] self
-    def remove_default
-      @default_formatter = nil
-      self
-    end
-
-    # Add a formatter for specific tag names or object classes. This can either be a Lumberjack::Formatter
-    # or an object that responds to `call` or a block. The formatter will be applied if it matches either a tag name
-    # or if the tag value is an instance of a registered class. Tag name formatters will take precedence
-    # over class formatters. The default formatter will not be applied to a value if a tag formatter
-    # is applied to it.
-    #
-    # Name formatters can be applied to nested hashes using dot syntax. For example, if you add a formatter
-    # for "foo.bar", it will be applied to the value of the "bar" key in the "foo" tag if that value is a hash.
-    #
-    # Class formatters will be applied recursively to nested hashes and arrays.
-    #
-    # @param names_or_classes [String, Module, Array<String, Module>] The tag names or object classes
-    #   to apply the formatter to.
-    # @param formatter [Lumberjack::Formatter, #call, nil] The formatter to use.
-    #    If this is nil, then the block will be used as the formatter.
-    # @return [Lumberjack::TagFormatter] self
-    #
-    # @example
-    #  tag_formatter.add("password", &:redact)
-    def add(names_or_classes, formatter = nil, &block)
-      formatter ||= block
-      formatter = dereference_formatter(formatter)
-      if formatter.nil?
-        remove(key)
-      else
-        Array(names_or_classes).each do |key|
-          if key.is_a?(Module)
-            @class_formatters[key] = formatter
-          else
-            @formatters[key.to_s] = formatter
-          end
-        end
-      end
-      self
-    end
-
-    # Remove formatters for specific tag names. The default formatter will still be applied.
-    #
-    # @param names_or_classes [String, Module, Array<String, Module>] The tag names or classes to remove the formatter from.
-    # @return [Lumberjack::TagFormatter] self
-    def remove(names_or_classes)
-      Array(names_or_classes).each do |key|
-        if key.is_a?(Module)
-          @class_formatters.delete(key)
-        else
-          @formatters.delete(key.to_s)
-        end
-      end
-      self
-    end
-
-    # Remove all formatters.
-    #
-    # @return [Lumberjack::TagFormatter] self
-    def clear
-      @default_formatter = nil
-      @formatters.clear
-      self
-    end
-
-    # Format a hash of tags using the formatters
+  # All functionality has been moved to {AttributeFormatter} with no changes to the API.
+  # Simply replace +TagFormatter+ with +AttributeFormatter+ in your code.
+  #
+  # @deprecated Use {Lumberjack::AttributeFormatter} instead.
+  # @see Lumberjack::AttributeFormatter
+  #
+  # @example Migration
+  #   # Old code (deprecated)
+  #   formatter = Lumberjack::TagFormatter.new
+  #
+  #   # New code
+  #   formatter = Lumberjack::AttributeFormatter.new
+  class TagFormatter < AttributeFormatter
+    # Create a new TagFormatter instance. Issues a deprecation warning and delegates
+    # to {AttributeFormatter}.
     #
-    # @param tags [Hash] The tags to format.
-    # @return [Hash] The formatted tags.
-    def format(tags)
-      return nil if tags.nil?
-      if @default_formatter.nil? && @formatters.empty? && @class_formatters.empty?
-        return tags
-      end
-
-      formatted_tags(tags)
-    end
-
-    private
-
-    def formatted_tags(tags, skip_classes: nil, prefix: nil)
-      formatted = {}
-
-      tags.each do |name, value|
-        name = name.to_s
-        formatted[name] = formatted_tag_value(name, value, skip_classes: skip_classes, prefix: prefix)
-      end
-
-      formatted
-    end
-
-    def formatted_tag_value(name, value, skip_classes: nil, prefix: nil)
-      prefixed_name = prefix ? "#{prefix}#{name}" : name
-      using_class_formatter = false
-
-      formatter = @formatters[prefixed_name]
-      if formatter.nil? && (skip_classes.nil? || !skip_classes.include?(value.class))
-        formatter = class_formatter(value.class)
-        using_class_formatter = true if formatter
-      end
-
-      formatter ||= @default_formatter
-
-      formatted_value = begin
-        if formatter.is_a?(Lumberjack::Formatter)
-          formatter.format(value)
-        elsif formatter.respond_to?(:call)
-          formatter.call(value)
-        else
-          value
-        end
-      rescue SystemStackError, StandardError => e
-        error_message = e.class.name
-        error_message = "#{error_message} #{e.message}" if e.message && e.message != ""
-        warn("<Error formatting #{value.class.name}: #{error_message}>")
-        "<Error formatting #{value.class.name}: #{error_message}>"
-      end
-
-      if formatted_value.is_a?(Enumerable)
-        skip_classes ||= []
-        skip_classes << value.class if using_class_formatter
-        sub_prefix = "#{prefixed_name}."
-
-        formatted_value = if formatted_value.is_a?(Hash)
-          formatted_tags(formatted_value, skip_classes: skip_classes, prefix: sub_prefix)
-        else
-          formatted_value.collect do |item|
-            formatted_tag_value(nil, item, skip_classes: skip_classes, prefix: sub_prefix)
-          end
-        end
-      end
-
-      formatted_value
-    end
-
-    def dereference_formatter(formatter)
-      if formatter.is_a?(TaggedLoggerSupport::Formatter)
-        formatter.__formatter
-      elsif formatter.is_a?(Symbol)
-        formatter_class_name = "#{formatter.to_s.gsub(/(^|_)([a-z])/) { |m| $~[2].upcase }}Formatter"
-        Formatter.const_get(formatter_class_name).new
-      else
-        formatter
-      end
-    end
-
-    def class_formatter(klass)
-      formatter = @class_formatters[klass]
-      return formatter if formatter
-
-      formatters = @class_formatters.select { |k, _| klass <= k }
-      return formatters.values.first if formatters.length <= 1
-
-      superclass = klass.superclass
-      while superclass
-        formatter = formatters[superclass]
-        return formatter if formatter
-        superclass = superclass.superclass
+    # @deprecated Use {Lumberjack::AttributeFormatter.new} instead.
+    def initialize
+      Utils.deprecated("Lumberjack::TagFormatter", "Use Lumberjack::AttributeFormatter instead.") do
+        super
       end
-
-      formatters.values.first
     end
   end
 end

data/lib/lumberjack/tags.rb

@@ -6,36 +6,30 @@ module Lumberjack
       # Transform hash keys to strings. This method exists for optimization and backward compatibility.
       # If a hash already has string keys, it will be returned as is.
       #
-      # @param [Hash] hash The hash to transform.
+      # @param hash [Hash] The hash to transform.
       # @return [Hash] The hash with string keys.
+      # @deprecated No longer supported
       def stringify_keys(hash)
-        return nil if hash.nil?
-        if hash.keys.all? { |key| key.is_a?(String) }
-          hash
-        else
-          hash.transform_keys(&:to_s)
+        Utils.deprecated("Lumberjack::Tags.stringify_keys", "Lumberjack::Tags.stringify_keys is no longer supported and will be removed in version 2.1") do
+          return nil if hash.nil?
+
+          if hash.keys.all? { |key| key.is_a?(String) }
+            hash
+          else
+            hash.transform_keys(&:to_s)
+          end
         end
       end
 
-      # Ensure keys are strings and expand any values in a hash that are Proc's by calling them and replacing
-      # the value with the result. This allows setting global tags with runtime values.
+      # Alias to AttributesHelper.expand_runtime_values
       #
-      # @param [Hash] hash The hash to transform.
+      # @param hash [Hash] The hash to transform.
       # @return [Hash] The hash with string keys and expanded values.
+      # @deprecated Use {Lumberjack::AttributesHelper.expand_runtime_values} instead.
       def expand_runtime_values(hash)
-        return nil if hash.nil?
-        if hash.all? { |key, value| key.is_a?(String) && !value.is_a?(Proc) }
-          return hash
-        end
-
-        copy = {}
-        hash.each do |key, value|
-          if value.is_a?(Proc) && (value.arity == 0 || value.arity == -1)
-            value = value.call
-          end
-          copy[key.to_s] = value
+        Utils.deprecated("Lumberjack::Tags.expand_runtime_values", "Lumberjack::Tags.expand_runtime_values is deprecated and will be removed in version 2.1; use Lumberjack::AttributesHelper.expand_runtime_values instead.") do
+          AttributesHelper.expand_runtime_values(hash)
         end
-        copy
       end
     end
   end