lumberjack 1.0.0

data/lib/lumberjack/device/writer.rb

@@ -0,0 +1,119 @@
+module Lumberjack
+  class Device
+    # This logging device writes log entries as strings to an IO stream.
+    class Writer < Device
+      DEFAULT_FIRST_LINE_TEMPLATE = "[:time :severity :progname(:pid) #:unit_of_work_id] :message".freeze
+      DEFAULT_ADDITIONAL_LINES_TEMPLATE = "#{Lumberjack::LINE_SEPARATOR}> [#:unit_of_work_id] :message".freeze
+
+      # The size of the internal buffer. Defaults to 32K.
+      attr_accessor :buffer_size
+      
+      # Internal buffer to batch writes to the stream.
+      class Buffer # :nodoc:
+        attr_reader :size
+        
+        def initialize
+          @values = []
+          @size = 0
+        end
+        
+        def <<(string)
+          @values << string
+          @size += string.size
+        end
+        
+        def empty?
+          @values.empty?
+        end
+        
+        def join(delimiter)
+          @values.join(delimiter)
+        end
+        
+        def clear
+          @values = []
+          @size = 0
+        end
+      end
+      
+      # Create a new device to write log entries to a stream. Entries are converted to strings
+      # using a Template. The template can be specified using the <tt>:template</tt> option. This can
+      # either be a Proc or a string that will compile into a Template object.
+      #
+      # If the template is a Proc, it should accept an LogEntry as its only argument and output a string.
+      #
+      # If the template is a template string, it will be used to create a Template. The
+      # <tt>:additional_lines</tt> and <tt>:time_format</tt> options will be passed through to the
+      # Template constuctor.
+      #
+      # The default template is <tt>"[:time :severity :progname(:pid) #:unit_of_work_id] :message"</tt>
+      # with additional lines formatted as <tt>"\n [#:unit_of_work_id] :message"</tt>. The unit of
+      # work id will only appear if it is present.
+      def initialize(stream, options = {})
+        @lock = Mutex.new
+        @stream = stream
+        @stream.sync = true if @stream.respond_to?(:sync=)
+        @buffer = Buffer.new
+        @buffer_size = (options[:buffer_size] || 32 * 1024)
+        template = (options[:template] || DEFAULT_FIRST_LINE_TEMPLATE)
+        if template.respond_to?(:call)
+          @template = template
+        else
+          additional_lines = (options[:additional_lines] || DEFAULT_ADDITIONAL_LINES_TEMPLATE)
+          @template = Template.new(template, :additional_lines => additional_lines, :time_format => options[:time_format])
+        end
+      end
+      
+      # Write an entry to the stream. The entry will be converted into a string using the defined template.
+      def write(entry)
+        string = @template.call(entry)
+        @lock.synchronize do
+          @buffer << string
+        end
+        flush if @buffer.size >= buffer_size
+      end
+      
+      # Close the underlying stream.
+      def close
+        flush
+        stream.close
+      end
+      
+      # Flush the underlying stream.
+      def flush
+        @lock.synchronize do
+          before_flush
+          unless @buffer.empty?
+            out = @buffer.join(Lumberjack::LINE_SEPARATOR) << Lumberjack::LINE_SEPARATOR
+            begin
+              stream.write(out)
+              stream.flush
+            rescue => e
+              $stderr.write("#{e.class.name}: #{e.message}#{' at ' + e.backtrace.first if e.backtrace}")
+              $stderr.write(out)
+              $stderr.flush
+            end
+            @buffer.clear
+          end
+        end
+      end
+      
+      protected
+      
+      # Callback method that will be executed before data is written to the stream. Subclasses
+      # can override this method if needed.
+      def before_flush
+      end
+      
+      # Set the underlying stream.
+      def stream=(stream)
+        @stream = stream
+      end
+      
+      # Get the underlying stream.
+      def stream
+        @stream
+      end
+    end
+  end
+end

data/lib/lumberjack/formatter.rb

@@ -0,0 +1,76 @@
+module Lumberjack
+  # This class controls the conversion of log entry messages into strings. This allows you
+  # to log any object you want and have the logging system worry about converting it into a string.
+  #
+  # Formats are added to a Formatter by associating them with a class using the +add+ method. Formats
+  # are any object that responds to the +call+ method.
+  #
+  # By default, all object will be converted to strings using their inspect method except for Strings
+  # and Exceptions. Strings are not converted and Exceptions are converted using the ExceptionFormatter.
+  class Formatter
+    autoload :ExceptionFormatter, File.expand_path("../formatter/exception_formatter.rb", __FILE__)
+    autoload :InspectFormatter, File.expand_path("../formatter/inspect_formatter.rb", __FILE__)
+    autoload :PrettyPrintFormatter, File.expand_path("../formatter/pretty_print_formatter.rb", __FILE__)
+    autoload :StringFormatter, File.expand_path("../formatter/string_formatter.rb", __FILE__)
+    
+    def initialize
+      @class_formatters = {}
+      @default_formatter = InspectFormatter.new
+      add(Object, @default_formatter)
+      add(String, :string)
+      add(Exception, :exception)
+    end
+    
+    # Add a formatter for a class. The formatter can be specified as either an object
+    # that responds to the +call+ method or as a symbol representing one of the predefined
+    # formatters, or as a block to the method call.
+    #
+    # The predefined formatters are: <tt>:inspect</tt>, <tt>:string</tt>, <tt>:exception</tt>, and <tt>:pretty_print</tt>.
+    #
+    # === Examples
+    #
+    #   # Use a predefined formatter
+    #   formatter.add(MyClass, :pretty_print)
+    #
+    #   # Pass in a formatter object
+    #   formatter.add(MyClass, Lumberjack::Formatter::PrettyPrintFormatter.new)
+    #
+    #   # Use a block
+    #   formatter.add(MyClass){|obj| obj.humanize}
+    #
+    #   # Add statements can be chained together
+    #   formatter.add(MyClass, :pretty_print).add(YourClass){|obj| obj.humanize}
+    def add(klass, formatter = nil, &block)
+      formatter ||= block
+      if formatter.is_a?(Symbol)
+        formatter_class_name = "#{formatter.to_s.gsub(/(^|_)([a-z])/){|m| $~[2].upcase}}Formatter"
+        formatter = Formatter.const_get(formatter_class_name).new
+      end
+      @class_formatters[klass] = formatter
+      self
+    end
+    
+    # Remove the formatter associated with a class. Remove statements can be chained together.
+    def remove(klass)
+      @class_formatters.delete(klass)
+      self
+    end
+    
+    # Format a message object as a string.
+    def format(message)
+      formatter_for(message.class).call(message)
+    end
+
+    private
+    
+    # Find the formatter for a class by looking it up using the class hierarchy.
+    def formatter_for(klass) #:nodoc:
+      while klass != nil do
+        formatter = @class_formatters[klass]
+        return formatter if formatter
+        klass = klass.superclass
+      end
+      @default_formatter
+    end
+  end
+end

data/lib/lumberjack/formatter/exception_formatter.rb

@@ -0,0 +1,12 @@
+module Lumberjack
+  class Formatter
+    # Format an exception including the backtrace.
+    class ExceptionFormatter
+      def call(exception)
+        message = "#{exception.class.name}: #{exception.message}"
+        message << "#{Lumberjack::LINE_SEPARATOR}  #{exception.backtrace.join("#{Lumberjack::LINE_SEPARATOR}  ")}" if exception.backtrace
+        message
+      end
+    end
+  end
+end

data/lib/lumberjack/formatter/inspect_formatter.rb

@@ -0,0 +1,10 @@
+module Lumberjack
+  class Formatter
+    # Format an object by calling +inspect+ on it.
+    class InspectFormatter
+      def call(obj)
+        obj.inspect
+      end
+    end
+  end
+end

data/lib/lumberjack/formatter/pretty_print_formatter.rb

@@ -0,0 +1,23 @@
+require 'pp'
+require 'stringio'
+
+module Lumberjack
+  class Formatter
+    # Format an object with it's pretty print method.
+    class PrettyPrintFormatter
+      attr_accessor :width
+      
+      # Create a new formatter. The maximum width of the message can be specified with the width
+      # parameter (defaults to 79 characters).
+      def initialize(width = 79)
+        @width = width
+      end
+      
+      def call(obj)
+        s = StringIO.new
+        PP.pp(obj, s)
+        s.string.chomp
+      end
+    end
+  end
+end

data/lib/lumberjack/formatter/string_formatter.rb

@@ -0,0 +1,10 @@
+module Lumberjack
+  class Formatter
+    # Format an object by calling +to_s+ on it.
+    class StringFormatter
+      def call(obj)
+        obj.to_s
+      end
+    end
+  end
+end

data/lib/lumberjack/log_entry.rb

@@ -0,0 +1,36 @@
+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)
+      @time = time
+      @severity = (severity.is_a?(Fixnum) ? severity : Severity.label_to_level(severity))
+      @message = message
+      @progname = progname
+      @pid = pid
+      @unit_of_work_id = unit_of_work_id
+    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
+    end
+    
+    def inspect
+      to_s
+    end
+  end
+end

data/lib/lumberjack/logger.rb

@@ -0,0 +1,302 @@
+module Lumberjack
+  # Logger is a thread safe logging object. It has a compatible API with the Ruby
+  # standard library Logger class, the Log4r gem, and ActiveSupport::BufferedLogger.
+  #
+  # === Example
+  #
+  #   logger = Lumberjack::Logger.new
+  #   logger.info("Starting processing")
+  #   logger.debug("Processing options #{options.inspect}")
+  #   logger.fatal("OMG the application is on fire!")
+  #
+  # Log entries are written to a logging Device if their severity meets or exceeds the log level.
+  #
+  # Devices may use buffers internally and the log entries are not guaranteed to be written until you call
+  # the +flush+ method. Sometimes this can result in problems when trying to track down extraordinarily
+  # long running sections of code since it is likely that none of the messages logged before the long
+  # running code will appear in the log until the entire process finishes. You can set the +:flush_seconds+
+  # option on the constructor to force the device to be flushed periodically. This will create a new
+  # 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
+  # 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
+    include Severity
+    
+    # The Formatter object used to convert messages into strings.
+    attr_reader :formatter
+    
+    # The time that the device was last flushed.
+    attr_reader :last_flushed_at
+    
+    # The name of the program associated with log messages.
+    attr_writer :progname
+    
+    # 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.
+    # 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.
+    #
+    # 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
+      @lock = Mutex.new
+      @last_flushed_at = Time.now
+      @silencer = true
+      
+      create_flusher_thread(max_flush_seconds) if max_flush_seconds > 0
+    end
+    
+    # Get the level of severity of entries that are logged. Entries with a lower
+    # severity level will be ignored.
+    def level
+      thread_local_value(:lumberjack_logger_level) || @level
+    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
+    # +fatal+, +error+, +warn+, +info+, or +debug+.
+    #
+    # The severity can be passed in either as one of the Severity constants,
+    # or as a Severity label.
+    #
+    # === 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)
+      if severity && severity >= level
+        time = Time.now
+        message = yield if message.nil? && block_given?
+        message = @formatter.format(message)
+        entry = LogEntry.new(time, severity, message, progname || self.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
+      end
+      nil
+    end
+    
+    alias_method :log, :add
+    
+    # Flush the logging device.
+    def flush
+      device.flush
+      @last_flushed_at = Time.now
+      nil
+    end
+    
+    # Close the logging device.
+    def close
+      flush
+      @device.close if @device.respond_to?(:close)
+    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)
+    end
+    
+    # Return +true+ if +FATAL+ messages are being logged.
+    def fatal?
+      level <= FATAL
+    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)
+    end
+    
+    # Return +true+ if +ERROR+ messages are being logged.
+    def error?
+      level <= ERROR
+    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)
+    end
+    
+    # Return +true+ if +WARN+ messages are being logged.
+    def warn?
+      level <= WARN
+    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)
+    end
+    
+    # Return +true+ if +INFO+ messages are being logged.
+    def info?
+      level <= INFO
+    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)
+    end
+    
+    # Return +true+ if +DEBUG+ messages are being logged.
+    def debug?
+      level <= DEBUG
+    end
+    
+    # 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)
+    end
+    
+    alias_method :<<, :unknown
+    
+    # Set the minimum level of severity of messages to log.
+    def level=(severity)
+      if severity.is_a?(Fixnum)
+        @level = severity
+      else
+        @level = Severity.label_to_level(severity)
+      end
+    end
+    
+    # Silence the logger by setting a new log level inside a block. By default, only +ERROR+ or +FATAL+
+    # messages will be logged.
+    #
+    # === Example
+    #
+    #   logger.level = Lumberjack::Severity::INFO
+    #   logger.silence do
+    #     do_something   # Log level inside the block is +ERROR+
+    #   end
+    def silence(temporary_level = ERROR, &block)
+      if silencer
+        push_thread_local_value(:lumberjack_logger_level, temporary_level, &block)
+      else
+        yield
+      end
+    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.
+    def set_progname(value, &block)
+      if block
+        push_thread_local_value(:lumberjack_logger_progname, value, &block)
+      else
+        self.progname = value
+      end
+    end
+    
+    # Get the program name associated with log messages.
+    def progname
+      thread_local_value(:lumberjack_logger_progname) || @progname
+    end
+        
+    private
+    
+    # Set a local value for a thread tied to this object.
+    def set_thread_local_value(name, value) #:nodoc:
+      values = Thread.current[name]
+      unless values
+        values = {}
+        Thread.current[name] = values
+      end
+      if value.nil?
+        values.delete(self)
+        Thread.current[name] = nil if values.empty?
+      else
+        values[self] = value
+      end
+    end
+    
+    # Get a local value for a thread tied to this object.
+    def thread_local_value(name) #:nodoc:
+      values = Thread.current[name]
+      values[self] if values
+    end
+    
+    # Set a local value for a thread tied to this object within a block.
+    def push_thread_local_value(name, value) #:nodoc:
+      save_val = thread_local_value(name)
+      set_thread_local_value(name, value)
+      begin
+        yield
+      ensure
+        set_thread_local_value(name, save_val)
+      end
+    end
+    
+    # Open a logging device.
+    def open_device(device, options) #:nodoc:
+      if device.is_a?(Device)
+        device
+      elsif device.respond_to?(:write)
+        Device::Writer.new(device, options)
+      elsif device == :null
+        Device::Null.new
+      else
+        device = device.to_s
+        if options[:roll]
+          Device::DateRollingLogFile.new(device, options)
+        elsif options[:max_size]
+            Device::SizeRollingLogFile.new(device, options)
+        else
+          Device::LogFile.new(device, options)
+        end
+      end
+    end
+    
+    # Create a thread that will periodically call flush.
+    def create_flusher_thread(flush_seconds) #:nodoc:
+      if flush_seconds > 0
+        begin
+          logger = self
+          Thread.new do
+            loop do
+              begin
+                sleep(flush_seconds)
+                logger.flush if Time.now - logger.last_flushed_at >= flush_seconds
+              rescue => e
+                STDERR.puts("Error flushing log: #{e.inspect}")
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end