lumberjack 1.2.10 → 1.4.0

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,23 +45,49 @@ 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
 
     # 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
+      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
@@ -70,5 +97,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

data/lib/lumberjack/logger.rb

@@ -21,7 +21,7 @@ module Lumberjack
   # monitoring thread, but its use is highly recommended.
   #
   # Each log entry records the log message and severity along with the time it was logged, the
-  # program name, process id, and unit of work id. The message will be converted to a string, but
+  # program name, process id, and an optional hash of tags. The message will be converted to a string, but
   # otherwise, it is up to the device how these values are recorded. Messages are converted to strings
   # using a Formatter associated with the logger.
   class Logger
@@ -36,8 +36,8 @@ module Lumberjack
     # Set the name of the program to attach to log entries.
     attr_writer :progname
 
-    # The device being written to
-    attr_accessor :device
+    # The Formatter used only for log entry messages.
+    attr_accessor :message_formatter
 
     # The TagFormatter used for formatting tags for output
     attr_accessor :tag_formatter
@@ -51,31 +51,30 @@ module Lumberjack
     # If it is :null, it will be a Null device that won't record any output.
     # Otherwise, it will be assumed to be file path and wrapped in a Device::LogFile class.
     #
-    # This method can take the following options:
-    #
-    # * :level - The logging level below which messages will be ignored.
-    # * :formatter - The formatter to use for outputting messages to the log.
-    # * :datetime_format - The format to use for log timestamps.
-    # * :tag_formatter - The TagFormatter to use for formatting tags.
-    # * :progname - The name of the program that will be recorded with each log entry.
-    # * :flush_seconds - The maximum number of seconds between flush calls.
-    # * :roll - If the log device is a file path, it will be a Device::DateRollingLogFile if this is set.
-    # * :max_size - If the log device is a file path, it will be a Device::SizeRollingLogFile if this is set.
-    #
     # All other options are passed to the device constuctor.
     #
     # @param [Lumberjack::Device, Object, Symbol, String] device The device to log to.
     # @param [Hash] options The options for the logger.
+    # @option options [Integer, Symbol, String] :level The logging level below which messages will be ignored.
+    # @option options [Lumberjack::Formatter] :formatter The formatter to use for outputting messages to the log.
+    # @option options [String] :datetime_format The format to use for log timestamps.
+    # @option options [Lumberjack::Formatter] :message_formatter The MessageFormatter to use for formatting log messages.
+    # @option options [Lumberjack::TagFormatter] :tag_formatter The TagFormatter to use for formatting tags.
+    # @option options [String] :progname The name of the program that will be recorded with each log entry.
+    # @option options [Numeric] :flush_seconds The maximum number of seconds between flush calls.
+    # @option options [Boolean] :roll If the log device is a file path, it will be a Device::DateRollingLogFile if this is set.
+    # @option options [Integer] :max_size If the log device is a file path, it will be a Device::SizeRollingLogFile if this is set.
     def initialize(device = $stdout, options = {})
       options = options.dup
       self.level = options.delete(:level) || INFO
       self.progname = options.delete(:progname)
       max_flush_seconds = options.delete(:flush_seconds).to_f
 
-      @device = open_device(device, options) if device
+      @logdev = open_device(device, options) if device
       self.formatter = (options[:formatter] || Formatter.new)
-      @tag_formatter = (options[:tag_formatter] || TagFormatter.new)
-      time_format = (options[:datetime_format] || options[:time_format])
+      @message_formatter = options[:message_formatter] || Formatter.empty
+      @tag_formatter = options[:tag_formatter] || TagFormatter.new
+      time_format = options[:datetime_format] || options[:time_format]
       self.datetime_format = time_format if time_format
       @last_flushed_at = Time.now
       @silencer = true
@@ -85,6 +84,21 @@ module Lumberjack
       create_flusher_thread(max_flush_seconds) if max_flush_seconds > 0
     end
 
+    # Get the logging device that is used to write log entries.
+    #
+    # @return [Lumberjack::Device] The logging device.
+    def device
+      @logdev
+    end
+
+    # Set the logging device to a new device.
+    #
+    # @param [Lumberjack::Device] device The new logging device.
+    # @return [void]
+    def device=(device)
+      @logdev = device.nil? ? nil : open_device(device, {})
+    end
+
     # Get the timestamp format on the device if it has one.
     #
     # @return [String, nil] The timestamp format or nil if the device doesn't support it.
@@ -186,33 +200,39 @@ module Lumberjack
     #   logger.add_entry(:warn, "Request took a long time")
     #   logger.add_entry(Logger::DEBUG){"Start processing with options #{options.inspect}"}
     def add_entry(severity, message, progname = nil, tags = nil)
-      begin
-        severity = Severity.label_to_level(severity) unless severity.is_a?(Integer)
-        return true unless device && severity && severity >= level
+      severity = Severity.label_to_level(severity) unless severity.is_a?(Integer)
+      return true unless device && severity && severity >= level
+      return true if Thread.current[:lumberjack_logging]
 
-        return true if Thread.current[:lumberjack_logging]
-        Thread.current[:lumberjack_logging] = true
+      begin
+        Thread.current[:lumberjack_logging] = true # Prevent circular calls to add_entry
 
         time = Time.now
+
         message = message.call if message.is_a?(Proc)
-        message = formatter.format(message)
+        msg_class_formatter = message_formatter&.formatter_for(message.class)
+        if msg_class_formatter
+          message = msg_class_formatter.call(message)
+        elsif formatter
+          message = formatter.format(message)
+        end
+        message_tags = nil
+        if message.is_a?(Formatter::TaggedMessage)
+          message_tags = message.tags
+          message = message.message
+        end
+
         progname ||= self.progname
+        message_tags = Utils.flatten_tags(message_tags) if message_tags
 
         current_tags = self.tags
         tags = nil unless tags.is_a?(Hash)
-        if current_tags.empty?
-          tags = Tags.stringify_keys(tags) unless tags.nil?
-        else
-          tags = if tags.nil?
-            current_tags.dup
-          else
-            current_tags.merge(Tags.stringify_keys(tags))
-          end
-        end
+        tags = merge_tags(current_tags, tags)
+        tags = merge_tags(tags, message_tags) if message_tags
         tags = Tags.expand_runtime_values(tags)
         tags = tag_formatter.format(tags) if tag_formatter
 
-        entry = LogEntry.new(time, severity, message, progname, $$, tags)
+        entry = LogEntry.new(time, severity, message, progname, Process.pid, tags)
         write_to_device(entry)
       ensure
         Thread.current[:lumberjack_logging] = nil
@@ -361,7 +381,7 @@ module Lumberjack
 
     # Return +true+ if +INFO+ messages are being logged.
     #
-
+    # @return [Boolean]
     def info?
       level <= INFO
     end
@@ -441,6 +461,14 @@ module Lumberjack
       end
     end
 
+    # Provided for compatibility with ActiveSupport::LoggerThreadSafeLevel to temporarily set the log level.
+    #
+    # @param [Integer, String, Symbol] level The log level to use inside the block.
+    # @return [Object] The result of the block.
+    def log_at(level, &block)
+      with_level(level, &block)
+    end
+
     # Set the program name that is associated with log messages. If a block
     # is given, the program name will be valid only within the block.
     #
@@ -454,6 +482,15 @@ module Lumberjack
       end
     end
 
+    # Set the logger progname for the duration of the block.
+    #
+    # @yield [Object] The block to execute with the program name set.
+    # @param [String] value The program name to use.
+    # @return [Object] The result of the block.
+    def with_progname(value, &block)
+      set_progname(value, &block)
+    end
+
     # Get the program name associated with log messages.
     #
     # @return [String]
@@ -462,41 +499,68 @@ module Lumberjack
     end
 
     # Set a hash of tags on logger. If a block is given, the tags will only be set
-    # for the duration of the block. If this method is called inside such a block,
-    # the tags will only be defined on the tags in that block. When the parent block
-    # exits, all the tags will be reverted. If there is no block, then the tags will
-    # be defined as global and apply to all log statements.
+    # for the duration of the block. Otherwise the tags will be applied on the current
+    # logger context for the duration of that context.
+    #
+    # If there is no block or context, the tags will be applied to the global context.
+    # This behavior is deprecated. Use the `tag_globally` method to set global tags instead.
     #
     # @param [Hash] tags The tags to set.
     # @return [void]
     def tag(tags, &block)
-      tags = Tags.stringify_keys(tags)
       thread_tags = thread_local_value(:lumberjack_logger_tags)
       if block
-        merged_tags = (thread_tags ? thread_tags.merge(tags) : tags.dup)
+        merged_tags = (thread_tags ? thread_tags.dup : {})
+        TagContext.new(merged_tags).tag(tags)
         push_thread_local_value(:lumberjack_logger_tags, merged_tags, &block)
       elsif thread_tags
-        thread_tags.merge!(tags)
+        TagContext.new(thread_tags).tag(tags)
         nil
       else
-        @tags.merge!(tags)
-        nil
+        Utils.deprecated("Lumberjack::Logger#tag", "Lumberjack::Logger#tag must be called with a block or inside a context block. In version 2.0 it will no longer be used for setting global tags. Use Lumberjack::Logger#tag_globally instead.") do
+          tag_globally(tags)
+        end
       end
     end
 
-    # Remove a tag from the current tag context. If this is called inside a block to a
-    # call to `tag`, the tags will only be removed for the duration of that block. Otherwise
-    # they will be removed from the global tags.
+    # Set up a context block for the logger. All tags added within the block will be cleared when
+    # the block exits.
+    #
+    # @param [Proc] block The block to execute with the tag context.
+    # @return [TagContext] If no block is passed, then a Lumberjack::TagContext is returned that can be used
+    #   to interact with the tags (add, remove, etc.).
+    # @yield [TagContext] If a block is passed, it will be yielded a TagContext object that can be used to
+    #   add or remove tags within the context.
+    def context(&block)
+      if block
+        thread_tags = thread_local_value(:lumberjack_logger_tags)&.dup
+        thread_tags ||= {}
+        push_thread_local_value(:lumberjack_logger_tags, thread_tags) do
+          block.call(TagContext.new(thread_tags))
+        end
+      else
+        TagContext.new(thread_local_value(:lumberjack_logger_tags) || {})
+      end
+    end
+
+    # Add global tags to the logger that will appear on all log entries.
+    #
+    # @param [Hash] tags The tags to set.
+    # @return [void]
+    def tag_globally(tags)
+      TagContext.new(@tags).tag(tags)
+      nil
+    end
+
+    # Remove a tag from the current tag context. If this is called inside a tag context,
+    # the tags will only be removed for the duration of that block. Otherwise they will be removed
+    # from the global tags.
     #
     # @param [Array<String, Symbol>] tag_names The tags to remove.
     # @return [void]
     def remove_tag(*tag_names)
-      thread_tags = thread_local_value(:lumberjack_logger_tags)
-      if thread_tags
-        tag_names.each { |name| thread_tags.delete(name.to_s) }
-      else
-        tag_names.each { |name| @tags.delete(name.to_s) }
-      end
+      tags = thread_local_value(:lumberjack_logger_tags) || @tags
+      TagContext.new(tags).delete(*tag_names)
     end
 
     # Return all tags in scope on the logger including global tags set on the Lumberjack
@@ -513,6 +577,15 @@ module Lumberjack
       tags
     end
 
+    # Get the value of a tag by name from the current tag context.
+    #
+    # @param [String, Symbol] name The name of the tag to get.
+    # @return [Object, nil] The value of the tag or nil if the tag does not exist.
+    def tag_value(name)
+      name = name.join(".") if name.is_a?(Array)
+      TagContext.new(tags)[name]
+    end
+
     # Remove all tags on the current logger and logging context within a block.
     # You can still set new block scoped tags within theuntagged block and provide
     # tags on individual log methods.
@@ -533,6 +606,14 @@ module Lumberjack
       end
     end
 
+    # Return true if the thread is currently in a Lumberjack::Context block.
+    # When the logger is in a context block, tagging will only apply to that block.
+    #
+    # @return [Boolean]
+    def in_tag_context?
+      !!thread_local_value(:lumberjack_logger_tags)
+    end
+
     private
 
     # Dereference arguments to log calls so we can have methods with compatibility with ::Logger
@@ -560,6 +641,17 @@ module Lumberjack
       add_entry(severity, message, progname, tags)
     end
 
+    # Merge a tags hash into an existing tags hash.
+    def merge_tags(current_tags, tags)
+      if current_tags.nil? || current_tags.empty?
+        tags
+      elsif tags.nil?
+        current_tags
+      else
+        current_tags.merge(tags)
+      end
+    end
+
     # Set a local value for a thread tied to this object.
     def set_thread_local_value(name, value) # :nodoc:
       values = Thread.current[name]

data/lib/lumberjack/rack/context.rb

@@ -3,16 +3,35 @@
 module Lumberjack
   module Rack
     # Middleware to create a global context for Lumberjack for the scope of a rack request.
+    #
+    # 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.
     class Context
-      def initialize(app)
+      # @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)
         @app = app
+        @env_tags = env_tags
       end
 
       def call(env)
         Lumberjack.context do
+          apply_tags(env) if @env_tags
           @app.call(env)
         end
       end
+
+      private
+
+      def apply_tags(env)
+        tags = @env_tags.transform_values do |value|
+          value.is_a?(Proc) ? value.call(env) : value
+        end
+        Lumberjack.tag(tags)
+      end
     end
   end
 end

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)