logging 0.9.4 → 0.9.5

data/History.txt

@@ -1,3 +1,13 @@
+== 0.9.5 / 2009-01-25
+
+2 minor enhancements
+  - The pattern layout can output the current thread name
+    if set using Thread.current[:name]         [valodzka]
+  - Added buffered logging to all IO based loggers
+    (console, file, rolling file)
+1 bug fix
+  - Uncaught TimeoutError in the e-mail appender
+
 == 0.9.4 / 2008-10-04
 
 2 minor enhancements

data/README.rdoc

@@ -89,6 +89,14 @@ class names.
 Logging requires the "lockfile" gem to run and the "flexmock" gem to run the
 tests"
 
+== DEVELOPMENT REQUIREMENTS
+
+The Logging source code relies on the Mr Bones project for default rake tasks.
+You will need to install the Mr Bones gem if you want to build or test the
+logging gem.
+
+   gem install bones
+
 == LICENSE
 
 Ruby

data/Rakefile

@@ -1,5 +1,14 @@
 
-load 'tasks/setup.rb'
+begin
+  require 'bones'
+  Bones.setup
+rescue LoadError
+  begin
+    load 'tasks/setup.rb'
+  rescue LoadError
+    raise RuntimeError, '### please install the "bones" gem ###'
+  end
+end
 
 ensure_in_path 'lib'
 require 'logging'
@@ -14,11 +23,10 @@ PROJ.url = 'http://logging.rubyforge.org/'
 PROJ.rubyforge.name = 'logging'
 PROJ.version = Logging::VERSION
 PROJ.readme_file = 'README.rdoc'
+PROJ.ignore_file = '.gitignore'
 
-PROJ.exclude << %w[^tags$ ^tasks/archive ^coverage]
+PROJ.exclude << %w[^tags$]
 PROJ.rdoc.exclude << '^data'
-PROJ.rdoc.include << PROJ.readme_file
-PROJ.rdoc.main = PROJ.readme_file
 #PROJ.rdoc.dir = 'doc/rdoc'
 #PROJ.rdoc.remote_dir = 'rdoc'
 PROJ.rdoc.dir = 'doc'

data/lib/logging.rb

@@ -8,12 +8,16 @@ begin require 'fastthread'; rescue LoadError; end
 
 # TODO: Windows Log Service appender
 
+# TODO: Option to buffer log messages at the appender level
+#       extend the concept found in the e-mail appender into the other IO
+#       appenders
+
 #
 #
 module Logging
 
   # :stopdoc:
-  VERSION = '0.9.4'
+  VERSION = '0.9.5'
   LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
   PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
   WIN32 = %r/djgpp|(cyg|ms|bcc)win|mingw/ =~ RUBY_PLATFORM

data/lib/logging/appender.rb

@@ -219,6 +219,9 @@ class Appender
     return self if @closed
     ::Logging::Appender.remove(@name)
     @closed = true
+
+    sync {flush}
+
     if footer
       footer = @layout.footer
       unless footer.nil? || footer.empty?

data/lib/logging/appenders/buffering.rb

@@ -0,0 +1,167 @@
+
+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 )
+      @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
+
+
+  end  # module Buffering
+end  # module Logging::Appenders
+
+# EOF

data/lib/logging/appenders/email.rb

@@ -10,23 +10,20 @@ require 'time' # get rfc822 time format
 module Logging::Appenders
 
 class Email < ::Logging::Appender
+  include Buffering
 
   attr_reader :server, :port, :domain, :acct, :authtype, :subject
 
+  # TODO: make the from/to fields modifiable
+  #       possibly the subject, too
+
   def initialize( name, opts = {} )
     super(name, opts)
 
-    @buff = []
-    @buffsize = opts.getopt :buffsize, 100, :as => Integer
-
-    # get the immediate levels -- no buffering occurs at these levels, and
-    # an e-mail is sent as soon as possible
-    @immediate = []
-    opts.getopt(:immediate_at, '').split(',').each do |lvl|
-      num = ::Logging.level_num(lvl.strip)
-      next if num.nil?
-      @immediate[num] = true
-    end
+    af = opts.getopt(:buffsize) ||
+         opts.getopt(:buffer_size) ||
+         100
+    configure_buffering({:auto_flushing => af}.merge(opts))
 
     # get the SMTP parameters
     @from = opts.getopt(:from)
@@ -51,58 +48,7 @@ class Email < ::Logging::Appender
   # Create and send an email containing the current message buffer.
   #
   def flush
-    sync { send_mail }
-    self
-  end
-
-  # call-seq:
-  #    close( footer = true )
-  #
-  # Close the e-mail appender and then flush the message buffer. This will
-  # ensure that a final e-mail is sent with any remaining messages.
-  #
-  def close( footer = true )
-    super
-    flush
-  end
-
-  # cal-seq:
-  #    queued_messages    => integer
-  #
-  # Returns the number of messages in the buffer.
-  #
-  def queued_messages
-    @buff.length
-  end
-
-
-  private
-
-  # call-seq:
-  #    write( event )
-  #
-  # Write the given _event_ to the e-mail message buffer. The log event will
-  # be processed through the Layout associated with this appender.
-  #
-  def write( event )
-    immediate = false
-    str = if event.instance_of?(::Logging::LogEvent)
-        immediate = @immediate[event.level]
-        @layout.format(event)
-      else
-        event.to_s
-      end
-    return if str.empty?
-
-    @buff << str
-    send_mail if @buff.length >= @buffsize || immediate
-    self
-  end
-
-  # Connect to the mail server and send out any buffered messages.
-  #
-  def send_mail
-    return if @buff.empty?
+    return self if buffer.empty?
 
     ### build a mail header for RFC 822
     rfc822msg =  "From: #{@from}\n"
@@ -110,18 +56,17 @@ class Email < ::Logging::Appender
     rfc822msg << "Subject: #{@subject}\n"
     rfc822msg << "Date: #{Time.new.rfc822}\n"
     rfc822msg << "Message-Id: <#{"%.8f" % Time.now.to_f}@#{@domain}>\n\n"
-    rfc822msg << @buff.join
+    rfc822msg << buffer.join
 
     ### send email
-    begin 
-      Net::SMTP.start(*@params) {|smtp| smtp.sendmail(rfc822msg, @from, @to)}
-    rescue StandardError => err
-      self.level = :off
-      ::Logging.log_internal {'e-mail notifications have been disabled'}
-      ::Logging.log_internal(-2) {err}
-    ensure
-      @buff.clear
-    end
+    Net::SMTP.start(*@params) {|smtp| smtp.sendmail(rfc822msg, @from, @to)}
+    self
+  rescue StandardError, TimeoutError => err
+    self.level = :off
+    ::Logging.log_internal {'e-mail notifications have been disabled'}
+    ::Logging.log_internal(-2) {err}
+  ensure
+    buffer.clear
   end
 
 end   # class Email

data/lib/logging/appenders/io.rb

@@ -5,6 +5,7 @@ module Logging::Appenders
   # configured for writing.
   #
   class IO < ::Logging::Appender
+    include Buffering
 
     # call-seq:
     #    IO.new( name, io )
@@ -14,12 +15,14 @@ module Logging::Appenders
     # stream as the logging destination.
     #
     def initialize( name, io, opts = {} )
-      unless io.respond_to? :print
+      unless io.respond_to? :write
         raise TypeError, "expecting an IO object but got '#{io.class.name}'"
       end
 
       @io = io
-      @io.sync = true if @io.respond_to?('sync') rescue nil
+      @io.sync = true if @io.respond_to?(:sync) rescue nil
+
+      configure_buffering(opts)
       super(name, opts)
     end
 
@@ -33,7 +36,7 @@ module Logging::Appenders
     #
     def close( *args )
       return self if @io.nil?
-      super(*args)
+      super
       io, @io = @io, nil
       io.close unless [STDIN, STDERR, STDOUT].include?(io)
     rescue IOError => err
@@ -49,29 +52,15 @@ module Logging::Appenders
     #
     def flush
       return self if @io.nil?
+      @io.write(buffer.join) unless buffer.empty?
       @io.flush
       self
-    end
-
-
-    private
-
-    # call-seq:
-    #    write( event )
-    #
-    # Writes the given _event_ to the IO stream. If an +IOError+ is detected,
-    # than this appender will be turned off and the error reported.
-    #
-    def write( event )
-      begin
-        str = event.instance_of?(::Logging::LogEvent) ?
-              @layout.format(event) : event.to_s
-        return if str.empty?
-        @io.print str
-      rescue IOError
-        self.level = :off
-        raise
-      end
+    rescue StandardError => err
+      self.level = :off
+      ::Logging.log_internal {"appender #{name.inspect} has been disabled"}
+      ::Logging.log_internal(-2) {err}
+    ensure
+      buffer.clear
     end
 
   end  # class IO