lumberjack 1.2.9 → 1.3.0

data/lib/lumberjack/formatter/strip_formatter.rb

@@ -1,4 +1,4 @@
-# frozen_string_literals: true
+# frozen_string_literal: true
 
 module Lumberjack
   class Formatter

data/lib/lumberjack/formatter/structured_formatter.rb

@@ -1,4 +1,4 @@
-# frozen_string_literals: true
+# frozen_string_literal: true
 
 require "set"
 

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

@@ -1,4 +1,4 @@
-# frozen_string_literals: true
+# frozen_string_literal: true
 
 module Lumberjack
   class Formatter

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
@@ -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

@@ -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,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))
@@ -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,10 +68,15 @@ 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
-      tags_string = ""
+      tags_string = +""
       tags&.each { |name, value| tags_string << " #{name}:#{value.inspect}" }
       tags_string
     end

data/lib/lumberjack/logger.rb

@@ -1,4 +1,4 @@
-# frozen_string_literals: true
+# frozen_string_literal: true
 
 module Lumberjack
   # Logger is a thread safe logging object. It has a compatible API with the Ruby
@@ -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,23 @@ 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 = if device
+        open_device(device, options)
+      end
+    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.
@@ -118,15 +134,19 @@ module Lumberjack
     # @param [Integer, Symbol, String] value The severity level.
     # @return [void]
     def level=(value)
-      @level = if value.is_a?(Integer)
-        value
-      else
-        Severity.label_to_level(value)
-      end
+      @level = Severity.coerce(value)
     end
 
     alias_method :sev_threshold=, :level=
 
+    # Adjust the log level during the block execution for the current Fiber only.
+    #
+    # @param [Integer, Symbol, String] severity The severity level.
+    # @return [Object] The result of the block.
+    def with_level(severity, &block)
+      push_thread_local_value(:lumberjack_logger_level, Severity.coerce(severity), &block)
+    end
+
     # Set the Lumberjack::Formatter used to format objects for logging as messages.
     #
     # @param [Lumberjack::Formatter, Object] value The formatter to use.
@@ -190,25 +210,30 @@ module Lumberjack
         Thread.current[:lumberjack_logging] = true
 
         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
 
         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
@@ -437,6 +462,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)
+      silence(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.
     #
@@ -458,10 +491,11 @@ 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]
@@ -475,11 +509,22 @@ module Lumberjack
         thread_tags.merge!(tags)
         nil
       else
-        @tags.merge!(tags)
-        nil
+        Lumberjack::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
 
+    # 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)
+      tags = Tags.stringify_keys(tags)
+      @tags.merge!(tags)
+      nil
+    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.
@@ -509,6 +554,31 @@ 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)
+      all_tags = tags
+      return nil if tags.empty?
+
+      name = name.join(".") if name.is_a?(Array)
+      name = name.to_s
+      return all_tags[name] if all_tags.include?(name)
+
+      flattened_tags = Lumberjack::Utils.flatten_tags(all_tags)
+      return flattened_tags[name] if flattened_tags.include?(name)
+
+      flattened_tags.keys.select { |key| key.include?(".") }.each do |key|
+        parts = key.split(".")
+        while (subkey = parts.pop)
+          flattened_tags[parts.join(".")] = {subkey => flattened_tags[(parts + [subkey]).join(".")]}
+        end
+      end
+
+      flattened_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.
@@ -529,6 +599,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
@@ -556,6 +634,20 @@ 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 = 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
+    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

@@ -1,18 +1,37 @@
-# frozen_string_literals: true
+# frozen_string_literal: true
 
 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

@@ -1,16 +1,20 @@
-# frozen_string_literals: true
+# frozen_string_literal: true
 
 module Lumberjack
   module Rack
     # 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

@@ -1,10 +1,14 @@
-# frozen_string_literals: true
+# frozen_string_literal: true
 
 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/rack.rb

@@ -1,4 +1,4 @@
-# frozen_string_literals: true
+# frozen_string_literal: true
 
 module Lumberjack
   module Rack

data/lib/lumberjack/severity.rb

@@ -1,4 +1,4 @@
-# frozen_string_literals: true
+# frozen_string_literal: true
 
 module Lumberjack
   # The standard severity levels for logging messages.
@@ -29,6 +29,18 @@ module Lumberjack
       def label_to_level(label)
         SEVERITY_LABELS.index(label.to_s.upcase) || UNKNOWN
       end
+
+      # Coerce a value to a severity level.
+      #
+      # @param [Integer, String, Symbol] value The value to coerce.
+      # @return [Integer] The severity level.
+      def coerce(value)
+        if value.is_a?(Integer)
+          value
+        else
+          label_to_level(value)
+        end
+      end
     end
   end
 end