lumberjack 1.2.10 → 1.3.0

data/lib/lumberjack/rack/request_id.rb

@@ -5,12 +5,16 @@ module Lumberjack
     # Support for using the Rails ActionDispatch request id in the log.
     # The format is expected to be a random UUID and only the first chunk is used for terseness
     # if the abbreviated argument is true.
+    #
+    # @deprecated Use tags instead of request id for unit of work. Will be removed in version 2.0.
     class RequestId
       REQUEST_ID = "action_dispatch.request_id"
 
       def initialize(app, abbreviated = false)
-        @app = app
-        @abbreviated = abbreviated
+        Lumberjack::Utils.deprecated("Lumberjack::Rack::RequestId", "Lumberjack::Rack::RequestId will be removed in version 2.0") do
+          @app = app
+          @abbreviated = abbreviated
+        end
       end
 
       def call(env)

data/lib/lumberjack/rack/unit_of_work.rb

@@ -2,9 +2,13 @@
 
 module Lumberjack
   module Rack
+    # @deprecated Use the Lumberjack::Rack::Context middleware instead to set a global tag
+    # with an identifier to tie log entries together in a unit of work. Will be removed in version 2.0.
     class UnitOfWork
       def initialize(app)
-        @app = app
+        Lumberjack::Utils.deprecated("Lumberjack::Rack::UnitOfWork", "Lumberjack::Rack::UnitOfWork will be removed in version 2.0") do
+          @app = app
+        end
       end
 
       def call(env)

data/lib/lumberjack/tag_formatter.rb

@@ -11,13 +11,14 @@ module Lumberjack
   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 [Lumberjack::Formatter, #call, nil] formatter The formatter to use.
+    # @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)
@@ -35,22 +36,37 @@ module Lumberjack
       self
     end
 
-    # Add a formatter for specific tag names. This can either be a Lumberjack::Formatter
-    # or an object that responds to `call` or a block. The default formatter will not be
-    # applied.
+    # 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.
     #
-    # @param [String, Array<String>] names The tag names to apply the formatter to.
-    # @param [Lumberjack::Formatter, #call, nil] formatter The formatter to use.
+    # 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
-    def add(names, formatter = nil, &block)
+    #
+    # @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).each do |name|
-          @formatters[name.to_s] = formatter
+        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
@@ -58,11 +74,15 @@ module Lumberjack
 
     # Remove formatters for specific tag names. The default formatter will still be applied.
     #
-    # @param [String, Array<String>] names The tag names to remove the formatter from.
+    # @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)
-      Array(names).each do |name|
-        @formatters.delete(name.to_s)
+    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
@@ -78,28 +98,66 @@ module Lumberjack
 
     # Format a hash of tags using the formatters
     #
-    # @param [Hash] tags The tags to format.
+    # @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? || (@formatters.keys & tags.keys).empty?)
-        tags
+      if @default_formatter.nil? && @formatters.empty? && @class_formatters.empty?
+        return tags
+      end
+
+      formated_tags(tags)
+    end
+
+    private
+
+    def formated_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 = if formatter.is_a?(Lumberjack::Formatter)
+        formatter.format(value)
+      elsif formatter.respond_to?(:call)
+        formatter.call(value)
       else
-        formatted = {}
-        tags.each do |name, value|
-          formatter = (@formatters[name.to_s] || @default_formatter)
-          if formatter.is_a?(Lumberjack::Formatter)
-            value = formatter.format(value)
-          elsif formatter.respond_to?(:call)
-            value = formatter.call(value)
+        value
+      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)
+          formated_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
-          formatted[name.to_s] = value
         end
-        formatted
       end
-    end
 
-    private
+      formatted_value
+    end
 
     def dereference_formatter(formatter)
       if formatter.is_a?(TaggedLoggerSupport::Formatter)
@@ -111,5 +169,22 @@ module Lumberjack
         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
+      end
+
+      formatters.values.first
+    end
   end
 end

data/lib/lumberjack/tagged_logger_support.rb

@@ -46,7 +46,12 @@ module Lumberjack
         tagged_values = Array(tag_hash["tagged"] || self.tags["tagged"])
         tag_hash["tagged"] = tagged_values + [tag]
       end
-      tag(tag_hash, &block)
+
+      if block || in_tag_context?
+        tag(tag_hash, &block)
+      else
+        tag_globally(tag_hash)
+      end
     end
 
     def push_tags(*tags)

data/lib/lumberjack/tags.rb

@@ -12,14 +12,8 @@ module Lumberjack
         return nil if hash.nil?
         if hash.keys.all? { |key| key.is_a?(String) }
           hash
-        elsif hash.respond_to?(:transform_keys)
-          hash.transform_keys(&:to_s)
         else
-          copy = {}
-          hash.each do |key, value|
-            copy[key.to_s] = value
-          end
-          copy
+          hash.transform_keys(&:to_s)
         end
       end
 

data/lib/lumberjack/template.rb

@@ -99,7 +99,7 @@ module Lumberjack
       return [nil] * (tag_vars.size + 1) if tags.nil? || tags.size == 0
 
       tags_string = +""
-      tags.each do |name, value|
+      Lumberjack::Utils.flatten_tags(tags).each do |name, value|
         unless value.nil? || tag_vars.include?(name)
           value = value.to_s
           value = value.gsub(Lumberjack::LINE_SEPARATOR, " ") if value.include?(Lumberjack::LINE_SEPARATOR)

data/lib/lumberjack/utils.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Lumberjack
+  module Utils
+    UNDEFINED = Object.new.freeze
+    private_constant :UNDEFINED
+
+    NON_SLUGGABLE_PATTERN = /[^A-Za-z0-9_.-]+/.freeze
+    private_constant :NON_SLUGGABLE_PATTERN
+
+    @deprecations = nil
+    @deprecations_lock = nil
+    @hostname = UNDEFINED
+
+    class << self
+      # Print warning when deprecated methods are called the first time. This can be disabled
+      # by setting the environment variable `LUMBERJACK_NO_DEPRECATION_WARNINGS` to "true".
+      # You can see every usage of a deprecated method along with a full stack trace by setting
+      # the environment variable `VERBOSE_LUMBERJACK_DEPRECATION_WARNING` to "true".
+      #
+      # @param method [String] The name of the deprecated method.
+      # @param message [String] Optional message to include in the warning.
+      # @yield The block to execute after the warning.
+      def deprecated(method, message)
+        @deprecations_lock ||= Mutex.new
+        unless @deprecations&.include?(method)
+          @deprecations_lock.synchronize do
+            @deprecations ||= {}
+            unless @deprecations.include?(method)
+              trace = caller[3..-1]
+              unless ENV["VERBOSE_LUMBERJACK_DEPRECATION_WARNING"] == "true"
+                trace = [trace.first]
+                @deprecations[method] = true
+              end
+              message = "DEPRECATION WARNING: #{message} Called from #{trace.join("\n")}"
+              warn(message) unless ENV["LUMBERJACK_NO_DEPRECATION_WARNINGS"] == "true"
+            end
+          end
+        end
+
+        yield
+      end
+
+      # Get the hostname of the machine. The returned value will be in UTF-8 encoding.
+      #
+      # @return [String] The hostname of the machine.
+      def hostname
+        if @hostname.equal?(UNDEFINED)
+          @hostname = force_utf8(Socket.gethostname)
+        end
+        @hostname
+      end
+
+      # Set the hostname to a specific value. If this is not specified, it will use the system hostname.
+      #
+      # @param hostname [String]
+      # @return [void]
+      def hostname=(hostname)
+        @hostname = force_utf8(hostname)
+      end
+
+      # Generate a global process ID that includes the hostname and process ID.
+      #
+      # @return [String] The global process ID.
+      def global_pid
+        if hostname
+          "#{hostname}-#{Process.pid}"
+        else
+          Process.pid.to_s
+        end
+      end
+
+      # Generate a global thread ID that includes the global process ID and the thread name.
+      #
+      # @return [String] The global thread ID.
+      def global_thread_id
+        "#{global_pid}-#{thread_name}"
+      end
+
+      # Get the name of a thread. The value will be based on the thread's name if it exists.
+      # Otherwise a unique id is generated based on the thread's object id. Only alphanumeric
+      # characters, underscores, dashes, and periods are kept in thread name.
+      #
+      # @param thread [Thread] The thread to get the name for. Defaults to the current thread.
+      # @return [String] The name of the thread.
+      def thread_name(thread = Thread.current)
+        thread.name ? slugify(thread.name) : thread.object_id.to_s(36)
+      end
+
+      # Force encode a string to UTF-8. Any invalid byte sequences will be
+      # ignored and replaced with an empty string.
+      #
+      # @param str [String] The string to encode.
+      # @return [String] The UTF-8 encoded string.
+      def force_utf8(str)
+        return nil if str.nil?
+
+        str.dup.force_encoding("ASCII-8BIT").encode("UTF-8", invalid: :replace, undef: :replace, replace: "")
+      end
+
+      # Flatten a tag hash to a single level hash with dot notation for nested keys.
+      #
+      # @param tag_hash [Hash] The hash to flatten.
+      # @return [Hash] The flattened hash.
+      def flatten_tags(tag_hash)
+        return {} unless tag_hash.is_a?(Hash)
+
+        tag_hash.each_with_object({}) do |(key, value), result|
+          if value.is_a?(Hash)
+            value.each do |sub_key, sub_value|
+              result["#{key}.#{sub_key}"] = sub_value
+            end
+          else
+            result[key] = value
+          end
+        end
+      end
+
+      private
+
+      def slugify(str)
+        return nil if str.nil?
+
+        str = str.gsub(NON_SLUGGABLE_PATTERN, "-")
+        str.delete_prefix!("-")
+        str.chomp!("-")
+        str
+      end
+    end
+  end
+end

data/lib/lumberjack.rb

@@ -22,6 +22,7 @@ module Lumberjack
   require_relative "lumberjack/tagged_logging"
   require_relative "lumberjack/template"
   require_relative "lumberjack/rack"
+  require_relative "lumberjack/utils"
 
   class << self
     # Define a unit of work within a block. Within the block supplied to this
@@ -34,19 +35,23 @@ module Lumberjack
     # For the common use case of treating a single web request as a unit of work, see the
     # Lumberjack::Rack::UnitOfWork class.
     #
-    # @param [String] id The id for the unit of work.
+    # @param id [String] The id for the unit of work.
     # @return [void]
+    # @deprecated Use tags instead. This will be removed in version 2.0.
     def unit_of_work(id = nil)
-      id ||= SecureRandom.hex(6)
-      context do
-        context[:unit_of_work_id] = id
-        yield
+      Lumberjack::Utils.deprecated("Lumberjack.unit_of_work", "Lumberjack.unit_of_work will be removed in version 2.0. Use Lumberjack::Logger#tag(unit_of_work: id) instead.") do
+        id ||= SecureRandom.hex(6)
+        context do
+          context[:unit_of_work_id] = id
+          yield
+        end
       end
     end
 
     # Get the UniqueIdentifier for the current unit of work.
     #
     # @return [String, nil] The id for the current unit of work.
+    # @deprecated Use tags instead. This will be removed in version 2.0.
     def unit_of_work_id
       context[:unit_of_work_id]
     end

data/lumberjack.gemspec

@@ -4,7 +4,7 @@ Gem::Specification.new do |spec|
   spec.authors = ["Brian Durand"]
   spec.email = ["bbdurand@gmail.com"]
 
-  spec.summary = "A simple, powerful, and very fast logging utility that can be a drop in replacement for Logger or ActiveSupport::BufferedLogger."
+  spec.summary = "A simple, powerful, and fast logging utility with excellent structured logging support that can be a drop in replacement for the standard library Logger."
   spec.homepage = "https://github.com/bdurand/lumberjack"
   spec.license = "MIT"
 
@@ -25,7 +25,7 @@ Gem::Specification.new do |spec|
 
   spec.require_paths = ["lib"]
 
-  spec.required_ruby_version = ">= 2.3.0"
+  spec.required_ruby_version = ">= 2.5.0"
 
   spec.add_development_dependency "bundler"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lumberjack
 version: !ruby/object:Gem::Version
-  version: 1.2.10
+  version: 1.3.0
 platform: ruby
 authors:
 - Brian Durand
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-11-13 00:00:00.000000000 Z
+date: 2025-07-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -31,6 +31,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ARCHITECTURE.md
 - CHANGELOG.md
 - MIT_LICENSE.txt
 - README.md
@@ -50,11 +51,15 @@ files:
 - lib/lumberjack/formatter/exception_formatter.rb
 - lib/lumberjack/formatter/id_formatter.rb
 - lib/lumberjack/formatter/inspect_formatter.rb
+- lib/lumberjack/formatter/multiply_formatter.rb
 - lib/lumberjack/formatter/object_formatter.rb
 - lib/lumberjack/formatter/pretty_print_formatter.rb
+- lib/lumberjack/formatter/redact_formatter.rb
+- lib/lumberjack/formatter/round_formatter.rb
 - lib/lumberjack/formatter/string_formatter.rb
 - lib/lumberjack/formatter/strip_formatter.rb
 - lib/lumberjack/formatter/structured_formatter.rb
+- lib/lumberjack/formatter/tagged_message.rb
 - lib/lumberjack/formatter/truncate_formatter.rb
 - lib/lumberjack/log_entry.rb
 - lib/lumberjack/logger.rb
@@ -68,6 +73,7 @@ files:
 - lib/lumberjack/tagged_logging.rb
 - lib/lumberjack/tags.rb
 - lib/lumberjack/template.rb
+- lib/lumberjack/utils.rb
 - lumberjack.gemspec
 homepage: https://github.com/bdurand/lumberjack
 licenses:
@@ -81,16 +87,16 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: 2.5.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.20
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
-summary: A simple, powerful, and very fast logging utility that can be a drop in replacement
-  for Logger or ActiveSupport::BufferedLogger.
+summary: A simple, powerful, and fast logging utility with excellent structured logging
+  support that can be a drop in replacement for the standard library Logger.
 test_files: []