lumberjack 1.0.13 → 1.1.0

data/lib/lumberjack/formatter/date_time_formatter.rb

@@ -0,0 +1,26 @@
+# frozen_string_literals: true
+
+module Lumberjack
+  class Formatter
+    # Format a Date, Time, or DateTime object. If you don't specify a format in the constructor,
+    # it will use the ISO-8601 format.
+    class DateTimeFormatter
+            
+      attr_reader :format
+      
+      def initialize(format = nil)
+        @format = format.dup.to_s.freeze unless format.nil?
+      end
+      
+      def call(obj)
+        if @format && obj.respond_to?(:strftime)
+          obj.strftime(@format)
+        elsif obj.respond_to?(:iso8601)
+          obj.iso8601
+        else
+          obj.to_s
+        end
+      end
+    end
+  end
+end

data/lib/lumberjack/formatter/id_formatter.rb

@@ -0,0 +1,23 @@
+# frozen_string_literals: true
+
+module Lumberjack
+  class Formatter
+    # Format an object that has an id as a hash with keys for class and id. This formatter is useful
+    # as a default formatter for objects pulled from a data store. By default it will use :id as the
+    # id attribute.
+    class IdFormatter
+      def initialize(id_attribute = :id)
+        @id_attribute = id_attribute
+      end
+      
+      def call(obj)
+        if obj.respond_to?(@id_attribute)
+          id = obj.send(@id_attribute)
+          { "class" => obj.class.name, "id" => id }
+        else
+          obj.to_s
+        end
+      end
+    end
+  end
+end

data/lib/lumberjack/formatter/object_formatter.rb

@@ -0,0 +1,12 @@
+# frozen_string_literals: true
+
+module Lumberjack
+  class Formatter
+    # No-op formatter that just returns the object itself.
+    class ObjectFormatter
+      def call(obj)
+        obj
+      end
+    end
+  end
+end

data/lib/lumberjack/formatter/structured_formatter.rb

@@ -0,0 +1,31 @@
+# frozen_string_literals: true
+
+require "set"
+
+module Lumberjack
+  class Formatter
+    # Dereference arrays and hashes and recursively call formatters on each element.
+    class StructuredFormatter
+      def initialize(formatter = nil)
+        @formatter = formatter
+      end
+
+      def call(obj)        
+        if obj.is_a?(Hash)
+          hash = {}
+          references ||= Set.new
+          obj.each do |name, value|
+            hash[name.to_s] = call(value)
+          end
+          hash
+        elsif obj.is_a?(Enumerable)
+          obj.collect { |element| call(element) }
+        elsif @formatter
+          @formatter.format(obj)
+        else
+          obj
+        end
+      end
+    end
+  end
+end

data/lib/lumberjack/log_entry.rb

@@ -4,35 +4,60 @@ module Lumberjack
   # An entry in a log is a data structure that captures the log message as well as
   # information about the system that logged the message.
   class LogEntry
-    attr_accessor :time, :message, :severity, :progname, :pid, :unit_of_work_id
-    
-    TIME_FORMAT = "%Y-%m-%dT%H:%M:%S".freeze
-    
-    def initialize(time, severity, message, progname, pid, unit_of_work_id)
+    attr_accessor :time, :message, :severity, :progname, :pid, :tags
+
+    TIME_FORMAT = "%Y-%m-%dT%H:%M:%S"
+
+    UNIT_OF_WORK_ID = "unit_of_work_id"
+
+    def initialize(time, severity, message, progname, pid, tags)
       @time = time
       @severity = (severity.is_a?(Integer) ? severity : Severity.label_to_level(severity))
       @message = message
       @progname = progname
       @pid = pid
-      @unit_of_work_id = unit_of_work_id
+      # backward compatibility with 1.0 API where the last argument was the unit of work id
+      if tags.nil? || tags.is_a?(Hash)
+        @tags = tags
+      else
+        @tags = { UNIT_OF_WORK_ID => tags }
+      end
     end
-    
+
     def severity_label
       Severity.level_to_label(severity)
     end
-    
+
     def to_s
-      buf = "[#{time.strftime(TIME_FORMAT)}.#{(time.usec / 1000.0).round.to_s.rjust(3, '0')} #{severity_label} #{progname}(#{pid})"
-      if unit_of_work_id
-        buf << " #"
-        buf << unit_of_work_id
-      end
-      buf << "] "
-      buf << message
+      "[#{time.strftime(TIME_FORMAT)}.#{(time.usec / 1000.0).round.to_s.rjust(3, '0')} #{severity_label} #{progname}(#{pid})#{tags_to_s}] #{message}"
     end
-    
+
     def inspect
       to_s
     end
+
+    # Deprecated - backward compatibility with 1.0 API
+    def unit_of_work_id
+      tags[UNIT_OF_WORK_ID] if tags
+    end
+
+    # Deprecated - backward compatibility with 1.0 API
+    def unit_of_work_id=(value)
+      if tags
+        tags[UNIT_OF_WORK_ID] = value
+      else
+        @tags = { UNIT_OF_WORK_ID => value }
+      end
+    end
+
+    private
+
+    def tags_to_s
+      tags_string = String.new
+      if tags
+        tags.each { |name, value| tags_string << " #{name}:#{value.inspect}" }
+      end
+      tags_string
+    end
   end
 end

data/lib/lumberjack/logger.rb

@@ -30,52 +30,62 @@ module Lumberjack
     # The time that the device was last flushed.
     attr_reader :last_flushed_at
 
-    # The name of the program associated with log messages.
+    # Set +silencer+ to false to disable silencing the log.
+    attr_accessor :silencer
+
+    # Set the name of the program to attach to log entries.
     attr_writer :progname
 
-    # The device being written to.
+    # The device being written to
     attr_reader :device
 
-    # Set +silencer+ to false to disable silencing the log.
-    attr_accessor :silencer
-
     # Create a new logger to log to a Device.
     #
     # The +device+ argument can be in any one of several formats.
     #
     # If it is a Device object, that object will be used.
     # If it has a +write+ method, it will be wrapped in a Device::Writer class.
-    # If it is <tt>:null</tt>, it will be a Null device that won't record any output.
+    # 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:
     #
-    # * <tt>:level</tt> - The logging level below which messages will be ignored.
-    # * <tt>:progname</tt> - The name of the program that will be recorded with each log entry.
-    # * <tt>:flush_seconds</tt> - The maximum number of seconds between flush calls.
-    # * <tt>:roll</tt> - If the log device is a file path, it will be a Device::DateRollingLogFile if this is set.
-    # * <tt>:max_size</tt> - If the log device is a file path, it will be a Device::SizeRollingLogFile if this is set.
+    # * :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.
+    # * :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.
     def initialize(device = STDOUT, options = {})
-      @thread_settings = {}
-
       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)
-      @_formatter = Formatter.new
+      @device = open_device(device, options) if device
+      @_formatter = (options[:formatter] || Formatter.new)
+      time_format = (options[:datetime_format] || options[:time_format])
+      self.datetime_format = time_format if time_format
       @last_flushed_at = Time.now
       @silencer = true
+      @tags = {}
 
       create_flusher_thread(max_flush_seconds) if max_flush_seconds > 0
     end
 
-    # Get the Formatter object used to convert messages into strings.
-    def formatter
-      @_formatter
+    # Get the timestamp format on the device if it has one.
+    def datetime_format
+      @device.datetime_format if @device.respond_to?(:datetime_format)
+    end
+
+    # Set the timestamp format on the device if it is supported.
+    def datetime_format=(format)
+      if @device.respond_to?(:datetime_format=)
+        @device.datetime_format = format
+      end
     end
 
     # Get the level of severity of entries that are logged. Entries with a lower
@@ -84,6 +94,30 @@ module Lumberjack
       thread_local_value(:lumberjack_logger_level) || @level
     end
 
+    alias_method :sev_threshold, :level
+
+    # Set the log level using either an integer level like Logger::INFO or a label like
+    # :info or "info"
+    def level=(value)
+      if value.is_a?(Integer)
+        @level = value
+      else
+        @level = Severity::label_to_level(value)
+      end
+    end
+
+    alias_method :sev_threshold=, :level=
+
+    # Set the Lumberjack::Formatter used to format objects for logging as messages.
+    def formatter=(value)
+      @_formatter = value
+    end
+
+    # Get the Lumberjack::Formatter used to format objects for logging as messages.
+    def formatter
+      @_formatter
+    end
+
     # Add a message to the log with a given severity. The message can be either
     # passed in the +message+ argument or supplied with a block. This method
     # is not normally called. Instead call one of the helper functions
@@ -94,36 +128,49 @@ module Lumberjack
     #
     # === Example
     #
-    #   logger.add(Lumberjack::Severity::ERROR, exception)
-    #   logger.add(Lumberjack::Severity::INFO, "Request completed")
-    #   logger.add(:warn, "Request took a long time")
-    #   logger.add(Lumberjack::Severity::DEBUG){"Start processing with options #{options.inspect}"}
-    def add(severity, message = nil, progname = nil)
-      severity = Severity.label_to_level(severity) if severity.is_a?(String) || severity.is_a?(Symbol)
+    #   logger.add_entry(Logger::ERROR, exception)
+    #   logger.add_entry(Logger::INFO, "Request completed")
+    #   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)
+      severity = Severity.label_to_level(severity) unless severity.is_a?(Integer)
 
-      return unless severity && severity >= level
+      return true unless @device && severity && severity >= level
 
       time = Time.now
+      message = message.call if message.is_a?(Proc)
+      message = formatter.format(message)
+      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
+        if tags.nil?
+          tags = current_tags.dup
+        else
+          tags = current_tags.merge(Tags.stringify_keys(tags))
+        end
+      end
+
+      entry = LogEntry.new(time, severity, message, progname, $$, tags)
+      write_to_device(entry)
+
+      true
+    end
+
+    # ::Logger compatible method to add a log entry.
+    def add(severity, message = nil, progname = nil, &block)
       if message.nil?
-        if block_given?
-          message = yield
+        if block
+          message = block
         else
           message = progname
           progname = nil
         end
       end
-
-      message = @_formatter.format(message)
-      progname ||= self.progname
-      entry = LogEntry.new(time, severity, message, progname, $$, Lumberjack.unit_of_work_id)
-      begin
-        device.write(entry)
-      rescue => e
-        $stderr.puts("#{e.class.name}: #{e.message}#{' at ' + e.backtrace.first if e.backtrace}")
-        $stderr.puts(entry.to_s)
-      end
-
-      nil
+      add_entry(severity, message, progname)
     end
 
     alias_method :log, :add
@@ -141,9 +188,13 @@ module Lumberjack
       @device.close if @device.respond_to?(:close)
     end
 
+    def reopen(logdev = nil)
+      device.reopen(logdev) if device.respond_to?(:reopen)
+    end
+
     # Log a +FATAL+ message. The message can be passed in either the +message+ argument or in a block.
-    def fatal(message = nil, progname = nil, &block)
-      add(FATAL, message, progname, &block)
+    def fatal(message_or_progname_or_tags = nil, progname_or_tags = nil, &block)
+      call_add_entry(FATAL, message_or_progname_or_tags, progname_or_tags, &block)
     end
 
     # Return +true+ if +FATAL+ messages are being logged.
@@ -152,8 +203,8 @@ module Lumberjack
     end
 
     # Log an +ERROR+ message. The message can be passed in either the +message+ argument or in a block.
-    def error(message = nil, progname = nil, &block)
-      add(ERROR, message, progname, &block)
+    def error(message_or_progname_or_tags = nil, progname_or_tags = nil, &block)
+      call_add_entry(ERROR, message_or_progname_or_tags, progname_or_tags, &block)
     end
 
     # Return +true+ if +ERROR+ messages are being logged.
@@ -162,8 +213,8 @@ module Lumberjack
     end
 
     # Log a +WARN+ message. The message can be passed in either the +message+ argument or in a block.
-    def warn(message = nil, progname = nil, &block)
-      add(WARN, message, progname, &block)
+    def warn(message_or_progname_or_tags = nil, progname_or_tags = nil, &block)
+      call_add_entry(WARN, message_or_progname_or_tags, progname_or_tags, &block)
     end
 
     # Return +true+ if +WARN+ messages are being logged.
@@ -172,8 +223,8 @@ module Lumberjack
     end
 
     # Log an +INFO+ message. The message can be passed in either the +message+ argument or in a block.
-    def info(message = nil, progname = nil, &block)
-      add(INFO, message, progname, &block)
+    def info(message_or_progname_or_tags = nil, progname_or_tags = nil, &block)
+      call_add_entry(INFO, message_or_progname_or_tags, progname_or_tags, &block)
     end
 
     # Return +true+ if +INFO+ messages are being logged.
@@ -182,8 +233,8 @@ module Lumberjack
     end
 
     # Log a +DEBUG+ message. The message can be passed in either the +message+ argument or in a block.
-    def debug(message = nil, progname = nil, &block)
-      add(DEBUG, message, progname, &block)
+    def debug(message_or_progname_or_tags = nil, progname_or_tags = nil, &block)
+      call_add_entry(DEBUG, message_or_progname_or_tags, progname_or_tags, &block)
     end
 
     # Return +true+ if +DEBUG+ messages are being logged.
@@ -193,19 +244,12 @@ module Lumberjack
 
     # Log a message when the severity is not known. Unknown messages will always appear in the log.
     # The message can be passed in either the +message+ argument or in a block.
-    def unknown(message = nil, progname = nil, &block)
-      add(UNKNOWN, message, progname, &block)
+    def unknown(message_or_progname_or_tags = nil, progname_or_tags = nil, &block)
+      call_add_entry(UNKNOWN, message_or_progname_or_tags, progname_or_tags, &block)
     end
 
-    alias_method :<<, :unknown
-
-    # Set the minimum level of severity of messages to log.
-    def level=(severity)
-      if severity.is_a?(Integer)
-        @level = severity
-      else
-        @level = Severity.label_to_level(severity)
-      end
+    def <<(msg)
+      add_entry(UNKNOWN, msg)
     end
 
     # Silence the logger by setting a new log level inside a block. By default, only +ERROR+ or +FATAL+
@@ -213,7 +257,7 @@ module Lumberjack
     #
     # === Example
     #
-    #   logger.level = Lumberjack::Severity::INFO
+    #   logger.level = Logger::INFO
     #   logger.silence do
     #     do_something   # Log level inside the block is +ERROR+
     #   end
@@ -240,8 +284,58 @@ module Lumberjack
       thread_local_value(:lumberjack_logger_progname) || @progname
     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.
+    def tag(tags, &block)
+      tags = Tags.stringify_keys(tags)
+      if block
+        thread_tags = thread_local_value(:lumberjack_logger_tags)
+        value = (thread_tags ? thread_tags.merge(tags) : tags)
+        push_thread_local_value(:lumberjack_logger_tags, value, &block)
+      else
+        @tags.merge!(tags)
+      end
+    end
+
+    # Return all tags in scope on the logger including global tags set on the Lumberjack
+    # context, tags set on the logger, and tags set on the current block for the logger
+    def tags
+      tags = {}
+      context_tags = Lumberjack.context_tags
+      tags.merge!(context_tags) if context_tags && !context_tags.empty?
+      tags.merge!(@tags) if !@tags.empty?
+      scope_tags = thread_local_value(:lumberjack_logger_tags)
+      tags.merge!(scope_tags) if scope_tags && !scope_tags.empty?
+      tags
+    end
+
     private
 
+    # Dereference arguments to log calls so we can have methods with compatibility with ::Logger
+    def call_add_entry(severity, message_or_progname_or_tags, progname_or_tags, &block) #:nodoc:
+      message = nil
+      progname = nil
+      tags = nil
+      if block
+        message = block
+        if message_or_progname_or_tags.is_a?(Hash)
+          tags = message_or_progname_or_tags
+          progname = progname_or_tags
+        else
+          progname = message_or_progname_or_tags
+          tags = progname_or_tags if progname_or_tags.is_a?(Hash)
+        end
+      else
+        message = message_or_progname_or_tags
+        if progname_or_tags.is_a?(Hash)
+          tags = progname_or_tags
+        else
+          progname = progname_or_tags
+        end
+      end
+      add_entry(severity, message, progname, 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]
@@ -276,7 +370,9 @@ module Lumberjack
 
     # Open a logging device.
     def open_device(device, options) #:nodoc:
-      if device.is_a?(Device)
+      if device.nil?
+        nil
+      elsif device.is_a?(Device)
         device
       elsif device.respond_to?(:write) && device.respond_to?(:flush)
         Device::Writer.new(device, options)
@@ -287,13 +383,22 @@ module Lumberjack
         if options[:roll]
           Device::DateRollingLogFile.new(device, options)
         elsif options[:max_size]
-            Device::SizeRollingLogFile.new(device, options)
+          Device::SizeRollingLogFile.new(device, options)
         else
           Device::LogFile.new(device, options)
         end
       end
     end
 
+    def write_to_device(entry) #:nodoc:
+      begin
+        @device.write(entry)
+      rescue => e
+        $stderr.puts("#{e.class.name}: #{e.message}#{' at ' + e.backtrace.first if e.backtrace}")
+        $stderr.puts(entry.to_s)
+      end
+    end
+
     # Create a thread that will periodically call flush.
     def create_flusher_thread(flush_seconds) #:nodoc:
       if flush_seconds > 0