lumberjack 1.2.7 → 1.4.2

data/lib/lumberjack/formatter/tagged_message.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Lumberjack
+  class Formatter
+    # This class can be used as the return value from a formatter `call` method to
+    # extract additional tags from an object being logged. This can be useful when there
+    # using structured logging to include important metadata in the log message.
+    #
+    # @example
+    #  # Automatically add tags with error details when logging an exception.
+    #  logger.add_formatter(Exception, ->(e) {
+    #    Lumberjack::Formatter::TaggedMessage.new(e.message, {
+    #      error: {
+    #        message: e.message,
+    #        class: e.class.name,
+    #        trace: e.backtrace
+    #      }
+    #    })
+    #  })
+    class TaggedMessage
+      attr_reader :message, :tags
+
+      # @param [Formatter] formatter The formatter to apply the transformation to.
+      # @param [Proc] transform The transformation function to apply to the formatted string.
+      def initialize(message, tags)
+        @message = message
+        @tags = tags || {}
+      end
+
+      def to_s
+        inspect
+      end
+
+      def inspect
+        {message: @message, tags: @tags}.inspect
+      end
+    end
+  end
+end

data/lib/lumberjack/formatter/truncate_formatter.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Lumberjack
+  class Formatter
+    # Truncate a string object to a specific length. This is useful
+    # for formatting messages when there is a limit on the number of
+    # characters that can be logged per message. This formatter should
+    # only be used when necessary since it is a lossy formatter.
+    #
+    # When a string is truncated, it will have a unicode ellipsis
+    # character (U+2026) appended to the end of the string.
+    class TruncateFormatter
+      # @param [Integer] length The maximum length of the string (defaults to 32K)
+      def initialize(length = 32768)
+        @length = length
+      end
+
+      def call(obj)
+        if obj.is_a?(String) && obj.length > @length
+          "#{obj[0, @length - 1]}…"
+        else
+          obj
+        end
+      end
+    end
+  end
+end

data/lib/lumberjack/formatter.rb

@@ -1,4 +1,4 @@
-# frozen_string_literals: true
+# frozen_string_literal: true
 
 module Lumberjack
   # This class controls the conversion of log entry messages into a loggable format. This allows you
@@ -12,25 +12,32 @@ module Lumberjack
   #
   # Enumerable objects (including Hash and Array) will call the formatter recursively for each element.
   class Formatter
-    require_relative "formatter/date_time_formatter.rb"
-    require_relative "formatter/exception_formatter.rb"
-    require_relative "formatter/id_formatter.rb"
-    require_relative "formatter/inspect_formatter.rb"
-    require_relative "formatter/object_formatter.rb"
-    require_relative "formatter/pretty_print_formatter.rb"
-    require_relative "formatter/string_formatter.rb"
-    require_relative "formatter/strip_formatter.rb"
-    require_relative "formatter/structured_formatter.rb"
+    require_relative "formatter/date_time_formatter"
+    require_relative "formatter/exception_formatter"
+    require_relative "formatter/id_formatter"
+    require_relative "formatter/inspect_formatter"
+    require_relative "formatter/multiply_formatter"
+    require_relative "formatter/object_formatter"
+    require_relative "formatter/pretty_print_formatter"
+    require_relative "formatter/redact_formatter"
+    require_relative "formatter/round_formatter"
+    require_relative "formatter/string_formatter"
+    require_relative "formatter/strip_formatter"
+    require_relative "formatter/structured_formatter"
+    require_relative "formatter/truncate_formatter"
+    require_relative "formatter/tagged_message"
 
     class << self
       # Returns a new empty formatter with no mapping. For historical reasons, a formatter
       # is initialized with mappings to help output objects as strings. This will return one
       # without the default mappings.
+      #
+      # @return [Lumberjack::Formatter] a new empty formatter
       def empty
         new.clear
       end
     end
-    
+
     def initialize
       @class_formatters = {}
       @module_formatters = {}
@@ -45,7 +52,17 @@ module Lumberjack
     # that responds to the +call+ method or as a symbol representing one of the predefined
     # formatters, or as a block to the method call.
     #
-    # The predefined formatters are: :inspect, :string, :exception, and :pretty_print.
+    # The predefined formatters are:
+    #   - :date_time
+    #   - :exception
+    #   - :id
+    #   - :inspect
+    #   - :object
+    #   - :pretty_print
+    #   - :string
+    #   - :strip
+    #   - :structured
+    #   - :truncate
     #
     # You can add multiple classes at once by passing an array of classes.
     #
@@ -53,7 +70,18 @@ module Lumberjack
     # help avoid loading dependency issues. This applies only to classes; modules cannot be
     # passed in as strings.
     #
-    # === Examples
+    # @param klass [Class, Module, String, Array<Class, Module, String>] The class or module to add a formatter for.
+    # @param formatter [Symbol, Class, String, #call] The formatter to use for the class.
+    #   If a symbol is passed in, it will be used to load one of the predefined formatters.
+    #   If a class is passed in, it will be initialized with the args passed in.
+    #   Otherwise, the object will be used as the formatter and must respond to call method.
+    # @param args [Array] Arguments to pass to the formatter when it is initialized.
+    # @yield [obj] A block that will be used as the formatter for the class.
+    # @yieldparam [Object] obj The object to format.
+    # @yieldreturn [String] The formatted string.
+    # @return [self] Returns itself so that add statements can be chained together.
+    #
+    # @example
     #
     #   # Use a predefined formatter
     #   formatter.add(MyClass, :pretty_print)
@@ -66,18 +94,27 @@ module Lumberjack
     #
     #   # Add statements can be chained together
     #   formatter.add(MyClass, :pretty_print).add(YourClass){|obj| obj.humanize}
-    def add(klass, formatter = nil, &block)
+    def add(klass, formatter = nil, *args, &block)
       formatter ||= block
       if formatter.nil?
         remove(klass)
       else
+        formatter_class_name = nil
         if formatter.is_a?(Symbol)
-          formatter_class_name = "#{formatter.to_s.gsub(/(^|_)([a-z])/){|m| $~[2].upcase}}Formatter"
-          formatter = Formatter.const_get(formatter_class_name).new
+          formatter_class_name = "#{formatter.to_s.gsub(/(^|_)([a-z])/) { |m| $~[2].upcase }}Formatter"
+        elsif formatter.is_a?(String)
+          formatter_class_name = formatter
+        end
+        if formatter_class_name
+          formatter = Formatter.const_get(formatter_class_name)
+        end
+
+        if formatter.is_a?(Class)
+          formatter = formatter.new(*args)
         end
-        
+
         Array(klass).each do |k|
-          if k.class == Module
+          if k.instance_of?(Module)
             @module_formatters[k] = formatter
           else
             k = k.name if k.is_a?(Class)
@@ -95,9 +132,12 @@ module Lumberjack
     # You can also pass class names as strings instead of the classes themselves. This can
     # help avoid loading dependency issues. This applies only to classes; modules cannot be
     # passed in as strings.
+    #
+    # @param klass [Class, Module, String, Array<Class, Module, String>] The class or module to remove the formatters for.
+    # @return [self] Returns itself so that remove statements can be chained together.
     def remove(klass)
       Array(klass).each do |k|
-        if k.class == Module
+        if k.instance_of?(Module)
           @module_formatters.delete(k)
         else
           k = k.name if k.is_a?(Class)
@@ -106,19 +146,38 @@ module Lumberjack
       end
       self
     end
-    
+
     # Remove all formatters including the default formatter. Can be chained to add method calls.
+    #
+    # @return [self] Returns itself so that clear statements can be chained together.
     def clear
       @class_formatters.clear
       @module_formatters.clear
       self
     end
 
-    # Format a message object as a string.
+    # Return true if their are no registered formatters.
+    #
+    # @return [Boolean] true if there are no registered formatters, false otherwise.
+    def empty?
+      @class_formatters.empty? && @module_formatters.empty?
+    end
+
+    # Format a message object by applying all formatters attached to it.
+    #
+    # @param message [Object] The message object to format.
+    # @return [Object] The formatted object.
     def format(message)
       formatter = formatter_for(message.class)
-      if formatter && formatter.respond_to?(:call)
-        formatter.call(message)
+      if formatter&.respond_to?(:call)
+        begin
+          formatter.call(message)
+        rescue SystemStackError, StandardError => e
+          error_message = e.class.name
+          error_message = "#{error_message} #{e.message}" if e.message && e.message != ""
+          warn("<Error formatting #{message.class.name}: #{error_message}>")
+          "<Error formatting #{message.class.name}: #{error_message}>"
+        end
       else
         message
       end
@@ -126,16 +185,25 @@ module Lumberjack
 
     # Compatibility with the Logger::Formatter signature. This method will just convert the message
     # object to a string and ignores the other parameters.
+    #
+    # @param severity [Integer, String, Symbol] The severity of the message.
+    # @param timestamp [Time] The time the message was logged.
+    # @param progname [String] The name of the program logging the message.
+    # @param msg [Object] The message object to format.
     def call(severity, timestamp, progname, msg)
-      "#{format(msg)}#{Lumberjack::LINE_SEPARATOR}"
+      formatted_message = format(msg)
+      formatted_message = formatted_message.message if formatted_message.is_a?(TaggedMessage)
+      "#{formatted_message}#{Lumberjack::LINE_SEPARATOR}"
     end
 
-    private
-
     # Find the formatter for a class by looking it up using the class hierarchy.
-    def formatter_for(klass) #:nodoc:
+    #
+    # @api private
+    def formatter_for(klass)
+      return nil if empty?
+
       check_modules = true
-      while klass != nil do
+      until klass.nil?
         formatter = @class_formatters[klass.name]
         return formatter if formatter
 

data/lib/lumberjack/log_entry.rb

@@ -1,4 +1,4 @@
-# frozen_string_literals: true
+# frozen_string_literal: true
 
 module Lumberjack
   # An entry in a log is a data structure that captures the log message as well as
@@ -8,8 +8,17 @@ module Lumberjack
 
     TIME_FORMAT = "%Y-%m-%dT%H:%M:%S"
 
+    # @deprecated Will be removed in version 2.0.
     UNIT_OF_WORK_ID = "unit_of_work_id"
 
+    # Create a new log entry.
+    #
+    # @param time [Time] The time the log entry was created.
+    # @param severity [Integer, String] The severity of the log entry.
+    # @param message [String] The message to log.
+    # @param progname [String] The name of the program that created the log entry.
+    # @param pid [Integer] The process id of the program that created the log entry.
+    # @param tags [Hash<String, Object>] A hash of tags to associate with the log entry.
     def initialize(time, severity, message, progname, pid, tags)
       @time = time
       @severity = (severity.is_a?(Integer) ? severity : Severity.label_to_level(severity))
@@ -17,10 +26,10 @@ module Lumberjack
       @progname = progname
       @pid = pid
       # backward compatibility with 1.0 API where the last argument was the unit of work id
-      if tags.nil? || tags.is_a?(Hash)
-        @tags = tags
-      else
-        @tags = { UNIT_OF_WORK_ID => tags }
+      @tags = if tags.is_a?(Hash)
+        compact_tags(tags)
+      elsif !tags.nil?
+        {UNIT_OF_WORK_ID => tags}
       end
     end
 
@@ -29,40 +38,102 @@ module Lumberjack
     end
 
     def to_s
-      "[#{time.strftime(TIME_FORMAT)}.#{(time.usec / 1000.0).round.to_s.rjust(3, '0')} #{severity_label} #{progname}(#{pid})#{tags_to_s}] #{message}"
+      "[#{time.strftime(TIME_FORMAT)}.#{(time.usec / 1000.0).round.to_s.rjust(3, "0")} #{severity_label} #{progname}(#{pid})#{tags_to_s}] #{message}"
     end
 
     def inspect
       to_s
     end
 
-    # Deprecated - backward compatibility with 1.0 API
+    # @deprecated - backward compatibility with 1.0 API. Will be removed in version 2.0.
     def unit_of_work_id
-      tags[UNIT_OF_WORK_ID] if tags
+      Lumberjack::Utils.deprecated("Lumberjack::LogEntry#unit_of_work_id", "Lumberjack::LogEntry#unit_of_work_id will be removed in version 2.0") do
+        tags[UNIT_OF_WORK_ID] if tags
+      end
     end
 
-    # Deprecated - backward compatibility with 1.0 API
+    # @deprecated - backward compatibility with 1.0 API. Will be removed in version 2.0.
     def unit_of_work_id=(value)
-      if tags
-        tags[UNIT_OF_WORK_ID] = value
-      else
-        @tags = { UNIT_OF_WORK_ID => value }
+      Lumberjack::Utils.deprecated("Lumberjack::LogEntry#unit_of_work_id=", "Lumberjack::LogEntry#unit_of_work_id= will be removed in version 2.0") do
+        if tags
+          tags[UNIT_OF_WORK_ID] = value
+        else
+          @tags = {UNIT_OF_WORK_ID => value}
+        end
       end
     end
-    
+
     # Return the tag with the specified name.
+    #
+    # @param name [String, Symbol] The tag name.
+    # @return [Object, nil] The tag value or nil if the tag does not exist.
     def tag(name)
-      tags[name.to_s] if tags
+      return nil if tags.nil?
+
+      TagContext.new(tags)[name]
+    end
+
+    # Helper method to expand the tags into a nested structure. Tags with dots in the name
+    # will be expanded into nested hashes.
+    #
+    # @return [Hash] The tags expanded into a nested structure.
+    #
+    # @example
+    #   entry = Lumberjack::LogEntry.new(Time.now, Logger::INFO, "test", "app", 1500, "a.b.c" => 1, "a.b.d" => 2)
+    #   entry.nested_tags # => {"a" => {"b" => {"c" => 1, "d" => 2}}}
+    def nested_tags
+      Utils.expand_tags(tags)
+    end
+
+    # Return true if the log entry has no message and no tags.
+    #
+    # @return [Boolean] True if the log entry is empty, false otherwise.
+    def empty?
+      (message.nil? || message == "") && (tags.nil? || tags.empty?)
     end
 
     private
 
     def tags_to_s
-      tags_string = String.new
-      if tags
-        tags.each { |name, value| tags_string << " #{name}:#{value.inspect}" }
-      end
+      tags_string = +""
+      tags&.each { |name, value| tags_string << " #{name}:#{value.inspect}" }
       tags_string
     end
+
+    def compact_tags(tags, seen = nil)
+      return {} if seen&.include?(tags.object_id)
+
+      delete_keys = nil
+      compacted_keys = nil
+
+      tags.each do |key, value|
+        if value.nil? || value == ""
+          delete_keys ||= []
+          delete_keys << key
+        elsif value.is_a?(Hash)
+          seen ||= Set.new
+          seen << tags.object_id
+          compacted_value = compact_tags(value, seen)
+          if compacted_value.empty?
+            delete_keys ||= []
+            delete_keys << key
+          elsif !value.equal?(compacted_value)
+            compacted_keys ||= []
+            compacted_keys << [key, compacted_value]
+          end
+        elsif value.is_a?(Array) && value.empty?
+          delete_keys ||= []
+          delete_keys << key
+        end
+      end
+
+      return tags if delete_keys.nil? && compacted_keys.nil?
+
+      tags = tags.dup
+      delete_keys&.each { |key| tags.delete(key) }
+      compacted_keys&.each { |key, value| tags[key] = value }
+
+      tags
+    end
   end
 end