sgeorgi-logging 1.4.2

data/lib/logging/appender.rb

@@ -0,0 +1,260 @@
+
+module Logging
+
+# The +Appender+ class is provides methods for appending log events to a
+# logging destination. The log events are formatted into strings using a
+# Layout.
+#
+# All other Appenders inherit from this class which provides stub methods.
+# Each subclass should provide a +write+ method that will write log
+# messages to the logging destination.
+#
+# A private +sync+ method is provided for use by subclasses. It is used to
+# synchronize writes to the logging destination, and can be used by
+# subclasses to synchronize the closing or flushing of the logging
+# destination.
+#
+class Appender
+
+  attr_reader :name, :layout, :level
+
+  # call-seq:
+  #    Appender.new( name )
+  #    Appender.new( name, :layout => layout )
+  #
+  # Creates a new appender using the given name. If no Layout is specified,
+  # then a Basic layout will be used. Any logging header supplied by the
+  # layout will be written to the logging destination when the Appender is
+  # created.
+  #
+  # Options:
+  #
+  #    :layout   => the layout to use when formatting log events
+  #    :level    => the level at which to log
+  #
+  def initialize( name, opts = {} )
+    ::Logging.init unless ::Logging.const_defined? :MAX_LEVEL_LENGTH
+
+    @name = name.to_s
+    @closed = false
+
+    self.layout = opts.getopt(:layout, ::Logging::Layouts::Basic.new)
+    self.level = opts.getopt(:level)
+
+    @mutex = ReentrantMutex.new
+    header = @layout.header
+
+    unless header.nil? || header.empty?
+      begin 
+        sync {write(header)}
+      rescue StandardError => err
+        ::Logging.log_internal(-2) {err}
+      end
+    end
+
+    ::Logging::Appenders[@name] = self
+  end
+
+  # call-seq:
+  #    append( event )
+  #
+  # Write the given _event_ to the logging destination. The log event will
+  # be processed through the Layout associated with the Appender.
+  #
+  def append( event )
+    if @closed
+      raise RuntimeError,
+            "appender '<#{self.class.name}: #{@name}>' is closed"
+    end
+
+    # only append if the event level is less than or equal to the configured
+    # appender level
+    unless @level > event.level
+      begin
+        sync {write(event)}
+      rescue StandardError => err
+        ::Logging.log_internal(-2) {err}
+      end
+    end
+
+    self
+  end
+
+  # call-seq:
+  #    appender << string
+  #
+  # Write the given _string_ to the logging destination "as is" -- no
+  # layout formatting will be performed.
+  #
+  def <<( str )
+    if @closed
+      raise RuntimeError,
+            "appender '<#{self.class.name}: #{@name}>' is closed"
+    end
+
+    unless @level >= ::Logging::LEVELS.length
+      begin
+        sync {write(str)}
+      rescue StandardError => err
+        ::Logging.log_internal(-2) {err}
+      end
+    end
+    self
+  end
+
+  # call-seq:
+  #    level = :all
+  #
+  # Set the level for this appender; log events below this level will be
+  # ignored by this appender. The level can be either a +String+, a
+  # +Symbol+, or a +Fixnum+. An +ArgumentError+ is raised if this is not
+  # the case.
+  #
+  # There are two special levels -- "all" and "off". The former will
+  # enable recording of all log events. The latter will disable the
+  # recording of all events.
+  #
+  # Example:
+  #
+  #    appender.level = :debug
+  #    appender.level = "INFO"
+  #    appender.level = 4
+  #    appender.level = 'off'
+  #    appender.level = :all
+  #
+  # These prodcue an +ArgumentError+
+  #
+  #    appender.level = Object
+  #    appender.level = -1
+  #    appender.level = 1_000_000_000_000
+  #
+  def level=( level )
+    lvl = case level
+          when String, Symbol; ::Logging::level_num(level)
+          when Fixnum; level
+          when nil; 0
+          else
+            raise ArgumentError,
+                  "level must be a String, Symbol, or Integer"
+          end
+    if lvl.nil? or lvl < 0 or lvl > ::Logging::LEVELS.length
+      raise ArgumentError, "unknown level was given '#{level}'"
+    end
+
+    @level = lvl
+  end
+
+  # call-seq
+  #    appender.layout = Logging::Layouts::Basic.new
+  #
+  # Sets the layout to be used by this appender.
+  #
+  def layout=( layout )
+    unless layout.kind_of? ::Logging::Layout
+      raise TypeError,
+            "#{layout.inspect} is not a kind of 'Logging::Layout'"
+    end
+    @layout = layout
+  end
+
+  # call-seq:
+  #    close( footer = true )
+  #
+  # Close the appender and writes the layout footer to the logging
+  # destination if the _footer_ flag is set to +true+. Log events will
+  # no longer be written to the logging destination after the appender
+  # is closed.
+  #
+  def close( footer = true )
+    return self if @closed
+    ::Logging::Appenders.remove(@name)
+    @closed = true
+
+    sync {flush}
+
+    if footer
+      footer = @layout.footer
+      unless footer.nil? || footer.empty?
+        begin
+          sync {write(footer)}
+        rescue StandardError => err
+          ::Logging.log_internal(-2) {err}
+        end
+      end
+    end
+    self
+  end
+
+  # call-seq:
+  #    closed?
+  #
+  # Returns +true+ if the appender has been closed; returns +false+
+  # otherwise. When an appender is closed, no more log events can be
+  # written to the logging destination.
+  #
+  def closed?
+    @closed
+  end
+
+  # Reopen the connection to the underlying logging destination. If the
+  # connection is currently closed then it will be opened. If the connection
+  # is currently open then it will be closed and immediately opened.
+  #
+  def reopen
+    @closed = false
+    self
+  end
+
+  # call-seq:
+  #    flush
+  #
+  # Call +flush+ to force an appender to write out any buffered log events.
+  # Similar to IO#flush, so use in a similar fashion.
+  #
+  def flush
+    self
+  end
+
+  # call-seq:
+  #     inspect    => string
+  #
+  # Returns a string representation of the appender.
+  #
+  def inspect
+    "<%s:0x%x name=\"%s\">" % [
+        self.class.name.sub(%r/^Logging::/, ''),
+        self.object_id,
+        self.name
+    ]
+  end
+
+
+  private 
+
+  # call-seq:
+  #    write( event )
+  #
+  # Writes the given _event_ to the logging destination. Subclasses should
+  # provide an implementation of this method. The _event_ can be either a
+  # LogEvent or a String. If a LogEvent, then it will be formatted using
+  # the layout given to the appender when it was created.
+  #
+  def write( event )
+    nil
+  end
+
+  # call-seq:
+  #    sync { block }
+  #
+  # Obtains an exclusive lock, runs the block, and releases the lock when
+  # the block completes. This method is re-entrant so that a single thread
+  # can call +sync+ multiple times without hanging the thread.
+  #
+  def sync( &block )
+    @mutex.synchronize(&block)
+  end
+
+end  # class Appender
+end  # module Logging
+
+# EOF

data/lib/logging/appenders.rb

@@ -0,0 +1,137 @@
+
+module Logging
+  module Appenders
+
+    # Accessor / Factory for the Email appender.
+    #
+    def email( *args )
+      return ::Logging::Appenders::Email if args.empty?
+      ::Logging::Appenders::Email.new(*args)
+    end
+
+    # Accessor / Factory for the File appender.
+    #
+    def file( *args )
+      return ::Logging::Appenders::File if args.empty?
+      ::Logging::Appenders::File.new(*args)
+    end
+
+    # Accessor / Factory for the Growl appender.
+    #
+    def growl( *args )
+      return ::Logging::Appenders::Growl if args.empty?
+      ::Logging::Appenders::Growl.new(*args)
+    end
+
+    # Accessor / Factory for the IO appender.
+    #
+    def io( *args )
+      return ::Logging::Appenders::IO if args.empty?
+      ::Logging::Appenders::IO.new(*args)
+    end
+
+    # Accessor / Factory for the RollingFile appender.
+    #
+    def rolling_file( *args )
+      return ::Logging::Appenders::RollingFile if args.empty?
+      ::Logging::Appenders::RollingFile.new(*args)
+    end
+
+    # Accessor / Factory for the Stderr appender.
+    #
+    def stderr( *args )
+      if args.empty?
+        return self['stderr'] || ::Logging::Appenders::Stderr.new
+      end
+      ::Logging::Appenders::Stderr.new(*args)
+    end
+
+    # Accessor / Factory for the Stdout appender.
+    #
+    def stdout( *args )
+      if args.empty?
+        return self['stdout'] || ::Logging::Appenders::Stdout.new
+      end
+      ::Logging::Appenders::Stdout.new(*args)
+    end
+
+    # Accessor / Factory for the StringIo appender.
+    #
+    def string_io( *args )
+      return ::Logging::Appenders::StringIo if args.empty?
+      ::Logging::Appenders::StringIo.new(*args)
+    end
+
+  if HAVE_SYSLOG
+    # Accessor / Factory for the Syslog appender.
+    #
+    def syslog( *args )
+      return ::Logging::Appenders::Syslog if args.empty?
+      ::Logging::Appenders::Syslog.new(*args)
+    end
+  end
+
+    # call-seq:
+    #    Appenders[name]
+    #
+    # Returns the appender instance stroed in the appender hash under the
+    # key _name_, or +nil+ if no appender has been created using that name.
+    #
+    def []( name ) @appenders[name] end
+
+    # call-seq:
+    #    Appenders[name] = appender
+    #
+    # Stores the given _appender_ instance in the appender hash under the
+    # key _name_.
+    #
+    def []=( name, value ) @appenders[name] = value end
+
+    # call-seq:
+    #    Appenders.remove( name )
+    #
+    # Removes the appender instance stored in the appender hash under the
+    # key _name_.
+    #
+    def remove( name ) @appenders.delete(name) end
+
+    # call-seq:
+    #    each {|appender| block}
+    #
+    # Yield each appender to the _block_.
+    #
+    def each( &block )
+      @appenders.values.each(&block)
+      return nil
+    end
+
+    # :stopdoc:
+    def reset
+      @appenders.values.each {|appender|
+        next if appender.nil?
+        appender.close
+      }
+      @appenders.clear
+      return nil
+    end
+    # :startdoc:
+
+    extend self
+    @appenders = Hash.new
+
+  end  # module Appenders
+end  # module Logging
+
+Logging.libpath {
+  require 'logging/appenders/buffering'
+  require 'logging/appenders/io'
+  require 'logging/appenders/console'
+  require 'logging/appenders/email'
+  require 'logging/appenders/file'
+  require 'logging/appenders/growl'
+  require 'logging/appenders/rolling_file'
+  require 'logging/appenders/string_io'
+  require 'logging/appenders/syslog'
+}
+
+# EOF

data/lib/logging/appenders/buffering.rb

@@ -0,0 +1,178 @@
+
+module Logging::Appenders
+
+  # The Buffering module is used to implement buffering of the log messages
+  # in a given appender. The size of the buffer can be specified, and the
+  # buffer can be configured to auto-flush at a given threshold. The
+  # threshold can be a single message or a very large number of messages.
+  #
+  # Log messages of a certain level can cause the buffer to be flushed
+  # immediately. If an error occurs, all previous messages and the error
+  # message will be written immediately to the logging destination if the
+  # buffer is configured to do so.
+  #
+  module Buffering
+
+    # Default buffer size
+    #
+    DEFAULT_BUFFER_SIZE = 500;
+
+    # The buffer holding the log messages
+    #
+    attr_reader :buffer
+
+    # The auto-flushing setting. When the buffer reaches this size, all
+    # messages will be be flushed automatically.
+    #
+    attr_reader :auto_flushing
+
+    # This message must be implemented by the including class. The method
+    # should write the contents of the buffer to the logging destination,
+    # and it should clear the buffer when done.
+    #
+    def flush
+      raise NotImplementedError
+    end
+
+    # Configure the levels that will trigger and immediate flush of the
+    # logging buffer. When a log event of the given level is seen, the
+    # buffer will be flushed immediately. Only the levels explicitly given
+    # in this assignment will flush the buffer; if an "error" message is
+    # configured to immediately flush the buffer, a "fatal" message will not
+    # even though it is a higher level. Both must be explicitly passed to
+    # this assignment.
+    #
+    # You can pass in a single leveal name or number, and array of level
+    # names or numbers, or a string containg a comma separated list of level
+    # names or numbers.
+    #
+    #   immediate_at = :error
+    #   immediate_at = [:error, :fatal]
+    #   immediate_at = "warn, error"
+    #
+    def immediate_at=( level )
+      @immediate ||= []
+      @immediate.clear
+
+      # get the immediate levels -- no buffering occurs at these levels, and
+      # a log message is written to the logging destination immediately
+      immediate_at =
+        case level
+        when String; level.split(',').map {|x| x.strip}
+        when Array; level
+        else Array(level) end
+      
+      immediate_at.each do |lvl|
+        num = ::Logging.level_num(lvl)
+        next if num.nil?
+        @immediate[num] = true
+      end
+    end
+
+    # Configure the auto-flushing period. Auto-flushing is used to flush the
+    # contents of the logging buffer to the logging destination
+    # automatically when the buffer reaches a certain threshold.
+    #
+    # By default, the auto-flushing will be configured to flush after each
+    # log message.
+    #
+    # The allowed settings are as follows:
+    #
+    #   N      : flush after every N messages (N is an integer)
+    #   true   : flush after each log message
+    #   false  OR
+    #   nil    OR
+    #   0      : only flush when the buffer is full (500 messages)
+    #
+    # If the default buffer size of 500 is too small, you can manuall
+    # configure to be as large as you want. This will consume more memory.
+    #
+    #   auto_flushing = 42_000
+    #
+    def auto_flushing=( period )
+      @auto_flushing =
+        case period
+        when true;             1
+        when false, nil, 0;    DEFAULT_BUFFER_SIZE
+        when Integer;          period
+        when String;           Integer(period)
+        else
+          raise ArgumentError,
+                "unrecognized auto_flushing period: #{period.inspect}"
+        end
+
+      if @auto_flushing < 0
+        raise ArgumentError,
+          "auto_flushing period cannot be negative: #{period.inspect}"
+      end
+    end
+
+
+    protected
+
+    # Configure the buffering using the arguments found in the give options
+    # hash. This method must be called in order to use the message buffer.
+    # The supported options are "immediate_at" and "auto_flushing". Please
+    # refer to the documentation for those methods to see the allowed
+    # options.
+    #
+    def configure_buffering( opts )
+      ::Logging.init unless ::Logging.const_defined? :MAX_LEVEL_LENGTH
+
+      @buffer = []
+      self.immediate_at = opts.getopt(:immediate_at, '')
+      self.auto_flushing = opts.getopt(:auto_flushing, true)
+    end
+
+    # Append the given event to the message buffer. The event can be either
+    # a string or a LogEvent object.
+    #
+    def add_to_buffer( event )
+      str = event.instance_of?(::Logging::LogEvent) ?
+            layout.format(event) : event.to_s
+      return if str.empty?
+
+      buffer << str
+      flush if buffer.length >= auto_flushing || immediate?(event)
+
+      self
+    end
+
+    # Returns true if the _event_ level matches one of the configured
+    # immediate logging levels. Otherwise returns false.
+    #
+    def immediate?( event )
+      return false unless event.respond_to? :level
+      @immediate[event.level]
+    end
+
+
+    private
+
+    # call-seq:
+    #    write( event )
+    #
+    # Writes the given _event_ to the logging destination. The _event_ can
+    # be either a LogEvent or a String. If a LogEvent, then it will be
+    # formatted using the layout given to the appender when it was created.
+    #
+    def write( event )
+      add_to_buffer event
+      self
+    end
+
+    #
+    # Explicit method name to call the write method from RollingFileAppender's write method
+    # to overcome "The newer patches for 1.8.7 introduced a regression that breaks
+    # calls to "super" within a block." (TwP on March 23rd, 2010)
+    #
+    def write_explicit( event )
+      add_to_buffer event
+      self
+    end
+
+
+  end  # module Buffering
+end  # module Logging::Appenders
+
+# EOF