lumberjack 1.2.7 → 1.4.2

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,22 +1,26 @@
-# 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)
         request_id = env[REQUEST_ID]
         if request_id && @abbreviated
-          request_id = request_id.split('-', 2).first
+          request_id = request_id.split("-", 2).first
         end
         Lumberjack.unit_of_work(request_id) do
           @app.call(env)

data/lib/lumberjack/rack/unit_of_work.rb

@@ -1,12 +1,16 @@
-# 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)
         Lumberjack.unit_of_work do
           @app.call(env)

data/lib/lumberjack/rack.rb

@@ -1,9 +1,9 @@
-# frozen_string_literals: true
+# frozen_string_literal: true
 
 module Lumberjack
   module Rack
-    require_relative "rack/unit_of_work.rb"
-    require_relative "rack/request_id.rb"
-    require_relative "rack/context.rb"
+    require_relative "rack/unit_of_work"
+    require_relative "rack/request_id"
+    require_relative "rack/context"
   end
 end

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.
@@ -11,17 +11,36 @@ module Lumberjack
     FATAL = ::Logger::Severity::FATAL
     UNKNOWN = ::Logger::Severity::UNKNOWN
 
-    SEVERITY_LABELS = %w(DEBUG INFO WARN ERROR FATAL UNKNOWN).freeze
+    SEVERITY_LABELS = %w[DEBUG INFO WARN ERROR FATAL UNKNOWN].freeze
 
     class << self
+      # Convert a severity level to a label.
+      #
+      # @param [Integer] severity The severity level to convert.
+      # @return [String] The severity label.
       def level_to_label(severity)
         SEVERITY_LABELS[severity] || SEVERITY_LABELS.last
       end
 
+      # Convert a severity label to a level.
+      #
+      # @param [String, Symbol] label The severity label to convert.
+      # @return [Integer] The severity level.
       def label_to_level(label)
         SEVERITY_LABELS.index(label.to_s.upcase) || UNKNOWN
       end
-    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

data/lib/lumberjack/tag_context.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Lumberjack
+  # A tag context provides an interface for manipulating a tag hash.
+  class TagContext
+    def initialize(tags)
+      @tags = tags
+    end
+
+    # Merge new tags into the context tags. Tag values will be flattened using dot notation
+    # on the keys. So `{ a: { b: 'c' } }` will become `{ 'a.b' => 'c' }`.
+    #
+    # If a block is given, then the tags will only be added for the duration of the block.
+    #
+    # @param tags [Hash] The tags to set.
+    # @return [void]
+    def tag(tags)
+      @tags.merge!(Utils.flatten_tags(tags))
+    end
+
+    # Get a tag value.
+    #
+    # @param name [String, Symbol] The tag key.
+    # @return [Object] The tag value.
+    def [](name)
+      return nil if @tags.empty?
+
+      name = name.to_s
+      return @tags[name] if @tags.include?(name)
+
+      # Check for partial matches in dot notation and return the hash representing the partial match.
+      prefix_key = "#{name}."
+      matching_tags = {}
+      @tags.each do |key, value|
+        if key.start_with?(prefix_key)
+          # Remove the prefix to get the relative key
+          relative_key = key[prefix_key.length..-1]
+          matching_tags[relative_key] = value
+        end
+      end
+
+      return nil if matching_tags.empty?
+      matching_tags
+    end
+
+    # Set a tag value.
+    #
+    # @param name [String, Symbol] The tag name.
+    # @param value [Object] The tag value.
+    # @return [void]
+    def []=(name, value)
+      if value.is_a?(Hash)
+        @tags.merge!(Utils.flatten_tags(name => value))
+      else
+        @tags[name.to_s] = value
+      end
+    end
+
+    # Remove tags from the context.
+    #
+    # @param names [Array<String, Symbol>] The tag names to remove.
+    # @return [void]
+    def delete(*names)
+      names.each do |name|
+        prefix_key = "#{name}."
+        @tags.delete_if { |k, _| k == name.to_s || k.start_with?(prefix_key) }
+      end
+      nil
+    end
+
+    # Return a copy of the tags as a hash.
+    #
+    # @return [Hash]
+    def to_h
+      @tags.dup
+    end
+  end
+end

data/lib/lumberjack/tag_formatter.rb

@@ -9,14 +9,18 @@ module Lumberjack
   # tag_formatter.add(["password", "email"]) { |value| "***" }
   # tag_formatter.add("finished_at", Lumberjack::Formatter::DateTimeFormatter.new("%Y-%m-%dT%H:%m:%S%z"))
   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 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)
       formatter ||= block
       formatter = dereference_formatter(formatter)
@@ -25,36 +29,67 @@ module Lumberjack
     end
 
     # Remove the default formatter.
+    #
+    # @return [Lumberjack::TagFormatter] self
     def remove_default
       @default_formatter = nil
       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.
-    def add(names, formatter = nil, &block)
+    # 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.
+    #
+    # 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
+    #
+    # @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
     end
 
     # Remove formatters for specific tag names. The default formatter will still be applied.
-    def remove(names)
-      Array(names).each do |name|
-        @formatters.delete(name.to_s)
+    #
+    # @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_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
 
     # Remove all formatters.
+    #
+    # @return [Lumberjack::TagFormatter] self
     def clear
       @default_formatter = nil
       @formatters.clear
@@ -62,37 +97,101 @@ module Lumberjack
     end
 
     # Format a hash of tags using the formatters
+    #
+    # @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
-      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)
-          end
-          formatted[name.to_s] = value
-        end
-        formatted
+      if @default_formatter.nil? && @formatters.empty? && @class_formatters.empty?
+        return tags
       end
+
+      formatted_tags(tags)
     end
 
     private
 
+    def formatted_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 = begin
+        if formatter.is_a?(Lumberjack::Formatter)
+          formatter.format(value)
+        elsif formatter.respond_to?(:call)
+          formatter.call(value)
+        else
+          value
+        end
+      rescue SystemStackError, StandardError => e
+        error_message = e.class.name
+        error_message = "#{error_message} #{e.message}" if e.message && e.message != ""
+        warn("<Error formatting #{value.class.name}: #{error_message}>")
+        "<Error formatting #{value.class.name}: #{error_message}>"
+      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)
+          formatted_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
+        end
+      end
+
+      formatted_value
+    end
+
     def dereference_formatter(formatter)
       if formatter.is_a?(TaggedLoggerSupport::Formatter)
         formatter.__formatter
       elsif formatter.is_a?(Symbol)
-        formatter_class_name = "#{formatter.to_s.gsub(/(^|_)([a-z])/){|m| $~[2].upcase}}Formatter"
+        formatter_class_name = "#{formatter.to_s.gsub(/(^|_)([a-z])/) { |m| $~[2].upcase }}Formatter"
         Formatter.const_get(formatter_class_name).new
       else
         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

@@ -6,7 +6,6 @@ require "forwardable"
 module Lumberjack
   # Methods to make Lumberjack::Logger API compatible with ActiveSupport::TaggedLogger.
   module TaggedLoggerSupport
-
     class Formatter < DelegateClass(Lumberjack::Formatter)
       extend Forwardable
       def_delegators :@logger, :tagged, :push_tags, :pop_tags, :clear_tags!
@@ -39,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)
@@ -55,13 +58,24 @@ module Lumberjack
     end
 
     def pop_tags(size = 1)
-      tagged_values = Array(@tags["tagged"])
-      tagged_values = (tagged_values.size > size ? tagged_values[0, tagged_values.size - size] : nil)
-      tag("tagged" => tagged_values)
+      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)
+
+      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/tagged_logging.rb

@@ -10,7 +10,7 @@ module Lumberjack
         base.singleton_class.send(:prepend, ClassMethods)
       end
     end
-    
+
     module ClassMethods
       def new(logger)
         if logger.is_a?(Lumberjack::Logger)

data/lib/lumberjack/tags.rb

@@ -5,29 +5,29 @@ module Lumberjack
     class << self
       # Transform hash keys to strings. This method exists for optimization and backward compatibility.
       # If a hash already has string keys, it will be returned as is.
+      #
+      # @param [Hash] hash The hash to transform.
+      # @return [Hash] The hash with string keys.
       def stringify_keys(hash)
         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
 
       # Ensure keys are strings and expand any values in a hash that are Proc's by calling them and replacing
       # the value with the result. This allows setting global tags with runtime values.
+      #
+      # @param [Hash] hash The hash to transform.
+      # @return [Hash] The hash with string keys and expanded values.
       def expand_runtime_values(hash)
         return nil if hash.nil?
         if hash.all? { |key, value| key.is_a?(String) && !value.is_a?(Proc) }
           return hash
         end
-        
+
         copy = {}
         hash.each do |key, value|
           if value.is_a?(Proc) && (value.arity == 0 || value.arity == -1)

data/lib/lumberjack/template.rb

@@ -1,4 +1,4 @@
-# frozen_string_literals: true
+# frozen_string_literal: true
 
 module Lumberjack
   # A template converts entries to strings. Templates can contain the following place holders to
@@ -14,7 +14,7 @@ module Lumberjack
   # If your tag name contains characters other than alpha numerics and the underscore, you must surround it
   # with curly brackets: `:{http.request-id}`.
   class Template
-    TEMPLATE_ARGUMENT_ORDER = %w(:time :severity :progname :pid :message :tags).freeze
+    TEMPLATE_ARGUMENT_ORDER = %w[:time :severity :progname :pid :message :tags].freeze
     MILLISECOND_TIME_FORMAT = "%Y-%m-%dT%H:%M:%S.%3N"
     MICROSECOND_TIME_FORMAT = "%Y-%m-%dT%H:%M:%S.%6N"
     PLACEHOLDER_PATTERN = /:(([a-z0-9_]+)|({[^}]+}))/i.freeze
@@ -30,6 +30,9 @@ module Lumberjack
     # specified precision.
     #
     # Messages will have white space stripped from both ends.
+    #
+    # @param [String] first_line The template to use to format the first line of a message.
+    # @param [Hash] options The options for the template.
     def initialize(first_line, options = {})
       @first_line_template, @first_line_tags = compile(first_line)
       additional_lines = options[:additional_lines] || "#{Lumberjack::LINE_SEPARATOR}:message"
@@ -39,6 +42,9 @@ module Lumberjack
       self.datetime_format = (options[:time_format] || :milliseconds)
     end
 
+    # Set the format used to format the time.
+    #
+    # @param [String] format The format to use to format the time.
     def datetime_format=(format)
       if format == :milliseconds
         format = MILLISECOND_TIME_FORMAT
@@ -48,11 +54,17 @@ module Lumberjack
       @time_formatter = Formatter::DateTimeFormatter.new(format)
     end
 
+    # Get the format used to format the time.
+    #
+    # @return [String]
     def datetime_format
       @time_formatter.format
     end
 
     # Convert an entry into a string using the template.
+    #
+    # @param [Lumberjack::LogEntry] entry The entry to convert to a string.
+    # @return [String] The entry converted to a string.
     def call(entry)
       return entry unless entry.is_a?(LogEntry)
 
@@ -86,8 +98,8 @@ module Lumberjack
     def tag_args(tags, tag_vars)
       return [nil] * (tag_vars.size + 1) if tags.nil? || tags.size == 0
 
-      tags_string = String.new
-      tags.each do |name, value|
+      tags_string = +""
+      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)
@@ -103,7 +115,7 @@ module Lumberjack
     end
 
     # Compile the template string into a value that can be used with sprintf.
-    def compile(template) #:nodoc:
+    def compile(template) # :nodoc:
       tag_vars = []
       template = template.gsub(PLACEHOLDER_PATTERN) do |match|
         var_name = match.sub("{", "").sub("}", "")