lumberjack 1.2.10 → 1.3.1

data/lib/lumberjack/context.rb

@@ -5,7 +5,7 @@ module Lumberjack
   class Context
     attr_reader :tags
 
-    # @param [Context] parent_context A parent context to inherit tags from.
+    # @param parent_context [Context] A parent context to inherit tags from.
     def initialize(parent_context = nil)
       @tags = {}
       @tags.merge!(parent_context.tags) if parent_context
@@ -13,7 +13,7 @@ module Lumberjack
 
     # Set tags on the context.
     #
-    # @param [Hash] tags The tags to set.
+    # @param tags [Hash] The tags to set.
     # @return [void]
     def tag(tags)
       tags.each do |key, value|
@@ -23,7 +23,7 @@ module Lumberjack
 
     # Get a context tag.
     #
-    # @param [String, Symbol] key The tag key.
+    # @param key [String, Symbol] The tag key.
     # @return [Object] The tag value.
     def [](key)
       @tags[key.to_s]
@@ -31,8 +31,8 @@ module Lumberjack
 
     # Set a context tag.
     #
-    # @param [String, Symbol] key The tag key.
-    # @param [Object] value The tag value.
+    # @param key [String, Symbol] The tag key.
+    # @param value [Object] The tag value.
     # @return [void]
     def []=(key, value)
       @tags[key.to_s] = value

data/lib/lumberjack/device/rolling_log_file.rb

@@ -18,7 +18,7 @@ module Lumberjack
       def initialize(path, options = {})
         @path = File.expand_path(path)
         @keep = options[:keep]
-        super(path, options)
+        super
         @file_inode = begin
           stream.lstat.ino
         rescue

data/lib/lumberjack/device/writer.rb

@@ -55,9 +55,8 @@ module Lumberjack
       # :additional_lines and :time_format options will be passed through to the
       # Template constuctor.
       #
-      # The default template is "[:time :severity :progname(:pid) #:unit_of_work_id] :message"
-      # with additional lines formatted as "\n [#:unit_of_work_id] :message". The unit of
-      # work id will only appear if it is present.
+      # The default template is "[:time :severity :progname(:pid)] :message"
+      # with additional lines formatted as "\n  :message".
       #
       # The size of the internal buffer in bytes can be set by providing :buffer_size (defaults to 32K).
       #
@@ -68,12 +67,12 @@ module Lumberjack
         @stream = stream
         @stream.sync = true if @stream.respond_to?(:sync=)
         @buffer = Buffer.new
-        @buffer_size = (options[:buffer_size] || 0)
-        template = (options[:template] || DEFAULT_FIRST_LINE_TEMPLATE)
+        @buffer_size = options[:buffer_size] || 0
+        template = options[:template] || DEFAULT_FIRST_LINE_TEMPLATE
         if template.respond_to?(:call)
           @template = template
         else
-          additional_lines = (options[:additional_lines] || DEFAULT_ADDITIONAL_LINES_TEMPLATE)
+          additional_lines = options[:additional_lines] || DEFAULT_ADDITIONAL_LINES_TEMPLATE
           @template = Template.new(template, additional_lines: additional_lines, time_format: options[:time_format])
         end
       end
@@ -150,6 +149,13 @@ module Lumberjack
         end
       end
 
+      # Return the underlying stream. Provided for API compatibility with Logger devices.
+      #
+      # @return [IO] The underlying stream.
+      def dev
+        @stream
+      end
+
       protected
 
       # Set the underlying stream.
@@ -163,8 +169,6 @@ module Lumberjack
       def write_to_stream(lines)
         return if lines.empty?
         lines = lines.first if lines.is_a?(Array) && lines.size == 1
-
-        out = nil
         out = if lines.is_a?(Array)
           "#{lines.join(Lumberjack::LINE_SEPARATOR)}#{Lumberjack::LINE_SEPARATOR}"
         else

data/lib/lumberjack/formatter/date_time_formatter.rb

@@ -16,7 +16,7 @@ module Lumberjack
         if @format && obj.respond_to?(:strftime)
           obj.strftime(@format)
         elsif obj.respond_to?(:iso8601)
-          obj.iso8601
+          obj.iso8601(6)
         else
           obj.to_s
         end

data/lib/lumberjack/formatter/multiply_formatter.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Lumberjack
+  class Formatter
+    # This formatter can be used to multiply a numeric value by a specified multiplier and
+    # optionally round to a specified number of decimal places.
+    class MultiplyFormatter
+      # @param multiplier [Numeric] The multiplier to apply to the value.
+      # @param decimals [Integer, nil] The number of decimal places to round the result to.
+      #   If nil, no rounding is applied.
+      def initialize(multiplier, decimals = nil)
+        @multiplier = multiplier
+        @decimals = decimals
+      end
+
+      def call(value)
+        return value unless value.is_a?(Numeric)
+
+        value *= @multiplier
+        value = value.round(@decimals) if @decimals
+        value
+      end
+    end
+  end
+end

data/lib/lumberjack/formatter/redact_formatter.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Lumberjack
+  class Formatter
+    # Log sensitive information in a redacted format showing the firat and last
+    # characters of the value, with the rest replaced by asterisks. The number of
+    # characters shown is dependent onthe length of the value; short values will
+    # not show any characters in order to avoid revealing too much information.
+    class RedactFormatter
+      def call(obj)
+        return obj unless obj.is_a?(String)
+
+        if obj.length > 8
+          "#{obj[0..1]}#{"*" * (obj.length - 4)}#{obj[-2..-1]}"
+        elsif obj.length > 5
+          "#{obj[0]}#{"*" * (obj.length - 2)}#{obj[-1]}"
+        else
+          "*****"
+        end
+      end
+    end
+  end
+end

data/lib/lumberjack/formatter/round_formatter.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Lumberjack
+  class Formatter
+    # Round numeric values to a set number of decimal places. This is useful when logging
+    # floating point numbers to reduce noise and rounding errors in the logs.
+    class RoundFormatter
+      def initialize(precision = 3)
+        @precision = precision
+      end
+
+      def call(obj)
+        if obj.is_a?(Numeric)
+          obj.round(@precision)
+        else
+          obj
+        end
+      end
+    end
+  end
+end

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.rb

@@ -16,12 +16,16 @@ module Lumberjack
     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
@@ -66,12 +70,12 @@ module Lumberjack
     # help avoid loading dependency issues. This applies only to classes; modules cannot be
     # passed in as strings.
     #
-    # @param [Class, Module, String, Array<Class, Module, String>] klass The class or module to add a formatter for.
-    # @param [Symbol, Class, String, #call] formatter The formatter to use for the class.
+    # @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 [Array] args Arguments to pass to the formatter when it is initialized.
+    # @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.
@@ -129,7 +133,7 @@ module Lumberjack
     # help avoid loading dependency issues. This applies only to classes; modules cannot be
     # passed in as strings.
     #
-    # @param [Class, Module, String, Array<Class, Module, String>] klass The class or module to remove the formatters for.
+    # @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|
@@ -152,9 +156,16 @@ module Lumberjack
       self
     end
 
+    # 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 [Object] message The message object to format.
+    # @param message [Object] The message object to format.
     # @return [Object] The formatted object.
     def format(message)
       formatter = formatter_for(message.class)
@@ -168,18 +179,22 @@ 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 [Integer, String, Symbol] severity The severity of the message.
-    # @param [Time] timestamp The time the message was logged.
-    # @param [String] progname The name of the program logging the message.
-    # @param [Object] msg The message object to format.
+    # @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
       until klass.nil?
         formatter = @class_formatters[klass.name]

data/lib/lumberjack/log_entry.rb

@@ -8,16 +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 [Integer, String] severity The severity of the log entry.
-    # @param [String] message The message to log.
-    # @param [String] progname The name of the program that created the log entry.
-    # @param [Integer] pid The process id of the program that created the log entry.
-    # @param [Hash] tags A hash of tags to associate with the 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))
@@ -25,9 +26,9 @@ module Lumberjack
       @progname = progname
       @pid = pid
       # backward compatibility with 1.0 API where the last argument was the unit of work id
-      @tags = if tags.nil? || tags.is_a?(Hash)
-        tags
-      else
+      @tags = if tags.is_a?(Hash)
+        compact_tags(tags)
+      elsif !tags.nil?
         {UNIT_OF_WORK_ID => tags}
       end
     end
@@ -44,17 +45,21 @@ module Lumberjack
       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
 
@@ -63,6 +68,11 @@ module Lumberjack
       tags[name.to_s] if tags
     end
 
+    # Return true if the log entry has no message and no tags.
+    def empty?
+      (message.nil? || message == "") && (tags.nil? || tags.empty?)
+    end
+
     private
 
     def tags_to_s
@@ -70,5 +80,37 @@ module Lumberjack
       tags&.each { |name, value| tags_string << " #{name}:#{value.inspect}" }
       tags_string
     end
+
+    def compact_tags(tags)
+      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)
+          compacted_value = compact_tags(value)
+          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