lumberjack 1.2.10 → 1.3.1

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,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.
@@ -194,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
@@ -441,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.
     #
@@ -462,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]
@@ -479,11 +509,31 @@ 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
 
+    # Set up a context block for the logger. All tags added within the block will be cleared when
+    # the block exits.
+    #
+    def context(&block)
+      thread_tags = thread_local_value(:lumberjack_logger_tags)&.dup
+      thread_tags ||= {}
+      push_thread_local_value(:lumberjack_logger_tags, thread_tags, &block)
+    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.
@@ -513,6 +563,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.
@@ -533,6 +608,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 +643,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

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

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

@@ -38,15 +38,19 @@ module Lumberjack
     end
 
     # Compatibility with ActiveSupport::TaggedLogging which only supports adding tags as strings.
-    # If a tag looks like "key:value"  or "key=value", it will be added as a key value pair.
-    # Otherwise it will be appended to a list named "tagged".
+    # Tags will be added to the "tagged" key in the logger's tags hash as an array.
     def tagged(*tags, &block)
-      tag_hash = {}
-      tags.flatten.each do |tag|
-        tagged_values = Array(tag_hash["tagged"] || self.tags["tagged"])
-        tag_hash["tagged"] = tagged_values + [tag]
+      tagged_values = Array(tag_value("tagged"))
+      flattened_tags = tags.flatten.collect(&:to_s).reject do |tag|
+        tag.respond_to?(:blank?) ? tag.blank? : tag.empty?
+      end
+      tagged_values += flattened_tags unless flattened_tags.empty?
+
+      if block || in_tag_context?
+        tag("tagged" => tagged_values, &block)
+      else
+        tag_globally("tagged" => tagged_values)
       end
-      tag(tag_hash, &block)
     end
 
     def push_tags(*tags)
@@ -54,13 +58,24 @@ module Lumberjack
     end
 
     def pop_tags(size = 1)
-      tagged_values = Array(@tags["tagged"])
+      tagged_values = tag_value("tagged")
+      return unless tagged_values.is_a?(Array)
+
       tagged_values = ((tagged_values.size > size) ? tagged_values[0, tagged_values.size - size] : nil)
-      tag("tagged" => tagged_values)
+
+      if in_tag_context?
+        tag("tagged" => tagged_values)
+      else
+        tag_globally("tagged" => tagged_values)
+      end
     end
 
     def clear_tags!
-      tag("tagged" => nil)
+      if in_tag_context?
+        tag("tagged" => nil)
+      else
+        tag_globally("tagged" => nil)
+      end
     end
   end
 end

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)