TwP-logging 0.9.7

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/console.rb

@@ -0,0 +1,62 @@
+
+require Logging.libpath(*%w[logging appenders io])
+
+module Logging::Appenders
+
+  # This class provides an Appender that can write to STDOUT.
+  #
+  class Stdout < ::Logging::Appenders::IO
+
+    # call-seq:
+    #    Stdout.new( name = 'stdout' )
+    #    Stdout.new( :layout => layout )
+    #    Stdout.new( name = 'stdout', :level => 'info' )
+    #
+    # Creates a new Stdout Appender. The name 'stdout' will be used unless
+    # another is given. Optionally, a layout can be given for the appender
+    # to use (otherwise a basic appender will be created) and a log level
+    # can be specified.
+    #
+    # Options:
+    #
+    #    :layout   => the layout to use when formatting log events
+    #    :level    => the level at which to log
+    #
+    def initialize( *args )
+      opts = Hash === args.last ? args.pop : {}
+      name = args.empty? ? 'stdout' : args.shift 
+
+      super(name, STDOUT, opts)
+    end
+  end  # class Stdout
+
+  # This class provides an Appender that can write to STDERR.
+  #
+  class Stderr < ::Logging::Appenders::IO
+
+    # call-seq:
+    #    Stderr.new( name = 'stderr' )
+    #    Stderr.new( :layout => layout )
+    #    Stderr.new( name = 'stderr', :level => 'warn' )
+    #
+    # Creates a new Stderr Appender. The name 'stderr' will be used unless
+    # another is given. Optionally, a layout can be given for the appender
+    # to use (otherwise a basic appender will be created) and a log level
+    # can be specified.
+    #
+    # Options:
+    #
+    #    :layout   => the layout to use when formatting log events
+    #    :level    => the level at which to log
+    #
+    def initialize( *args )
+      opts = Hash === args.last ? args.pop : {}
+      name = args.empty? ? 'stderr' : args.shift 
+
+      super(name, STDERR, opts)
+    end
+  end  # class Stderr
+
+end  # module Logging::Appenders
+
+# EOF

data/lib/logging/appenders/email.rb

@@ -0,0 +1,75 @@
+
+require 'net/smtp'
+require 'time' # get rfc822 time format
+
+# a replacement EmailOutputter.  This is essentially the default EmailOutptter from Log4r but with the following
+# changes:
+#   1) if there is data to send in an email, then do not send anything
+#   2) connect to the smtp server at the last minute, do not connect at startup and then send later on.
+#   3) Fix the To: field so that it looks alright.
+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)
+
+    af = opts.getopt(:buffsize) ||
+         opts.getopt(:buffer_size) ||
+         100
+    configure_buffering({:auto_flushing => af}.merge(opts))
+
+    # get the SMTP parameters
+    @from = opts.getopt(:from)
+    raise ArgumentError, 'Must specify from address' if @from.nil?
+
+    @to = opts.getopt(:to, '').split(',')
+    raise ArgumentError, 'Must specify recipients' if @to.empty?
+
+    @server   = opts.getopt :server, 'localhost'
+    @port     = opts.getopt :port, 25, :as => Integer
+    @domain   = opts.getopt(:domain, ENV['HOSTNAME']) || 'localhost.localdomain'
+    @acct     = opts.getopt :acct
+    @passwd   = opts.getopt :passwd
+    @authtype = opts.getopt :authtype, :cram_md5, :as => Symbol
+    @subject  = opts.getopt :subject, "Message of #{$0}"
+    @params   = [@server, @port, @domain, @acct, @passwd, @authtype]
+  end
+  
+  # call-seq:
+  #    flush
+  #
+  # Create and send an email containing the current message buffer.
+  #
+  def flush
+    return self if buffer.empty?
+
+    ### build a mail header for RFC 822
+    rfc822msg =  "From: #{@from}\n"
+    rfc822msg << "To: #{@to.join(",")}\n"
+    rfc822msg << "Subject: #{@subject}\n"
+    rfc822msg << "Date: #{Time.new.rfc822}\n"
+    rfc822msg << "Message-Id: <#{"%.8f" % Time.now.to_f}@#{@domain}>\n\n"
+    rfc822msg << buffer.join
+
+    ### send email
+    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
+end   # module Logging::Appenders
+
+# EOF

data/lib/logging/appenders/file.rb

@@ -0,0 +1,54 @@
+
+module Logging::Appenders
+
+  # This class provides an Appender that can write to a File.
+  #
+  class File < ::Logging::Appenders::IO
+
+    # call-seq:
+    #    File.assert_valid_logfile( filename )    => true
+    #
+    # Asserts that the given _filename_ can be used as a log file by ensuring
+    # that if the file exists it is a regular file and it is writable. If
+    # the file does not exist, then the directory is checked to see if it is
+    # writable.
+    #
+    # An +ArgumentError+ is raised if any of these assertions fail.
+    #
+    def self.assert_valid_logfile( fn )
+      if ::File.exist?(fn)
+        if not ::File.file?(fn)
+          raise ArgumentError, "#{fn} is not a regular file"
+        elsif not ::File.writable?(fn)
+          raise ArgumentError, "#{fn} is not writeable"
+        end
+      elsif not ::File.writable?(::File.dirname(fn))
+        raise ArgumentError, "#{::File.dirname(fn)} is not writable"
+      end
+      true
+    end
+
+    # call-seq:
+    #    File.new( name, :filename => 'file' )
+    #    File.new( name, :filename => 'file', :truncate => true )
+    #    File.new( name, :filename => 'file', :layout => layout )
+    #
+    # Creates a new File Appender that will use the given filename as the
+    # logging destination. If the file does not already exist it will be
+    # created. If the :truncate option is set to +true+ then the file will
+    # be truncated before writing begins; otherwise, log messages will be
+    # appened to the file.
+    #
+    def initialize( name, opts = {} )
+      @fn = opts.getopt(:filename, name)
+      raise ArgumentError, 'no filename was given' if @fn.nil?
+      self.class.assert_valid_logfile(@fn)
+      mode = opts.getopt(:truncate) ? 'w' : 'a'
+
+      super(name, ::File.new(@fn, mode), opts)
+    end
+
+  end  # class FileAppender
+end  # module Logging::Appenders
+
+# EOF

data/lib/logging/appenders/growl.rb

@@ -0,0 +1,197 @@
+
+module Logging::Appenders
+
+  # This class provides an Appender that can send notifications to the Growl
+  # notification system on Mac OS X.
+  #
+  # +growlnotify+ must be installed somewhere in the path in order for the
+  # appender to function properly.
+  #
+  class Growl < ::Logging::Appender
+
+    # :stopdoc:
+    ColoredRegexp = %r/\e\[([34][0-7]|[0-9])m/
+    # :startdoc:
+
+    # call-seq:
+    #    Growl.new( name, opts = {} )
+    #
+    # Create an appender that will log messages to the Growl framework on a
+    # Mac OS X machine.
+    #
+    def initialize( name, opts = {} )
+      super
+
+      @growl = "growlnotify -w -n \"#{@name}\" -t \"%s\" -m \"%s\" -p %d &"
+
+      @coalesce = opts.getopt(:coalesce, false)
+      @title_sep = opts.getopt(:separator)
+
+      # provides a mapping from the default Logging levels
+      # to the Growl notification levels
+      @map = [-2, -1, 0, 1, 2]
+
+      map = opts.getopt(:map)
+      self.map = map unless map.nil?
+      setup_coalescing if @coalesce
+
+      # make sure the growlnotify command can be called
+      unless system('growlnotify -v >> /dev/null 2>&1')
+        self.level = :off
+        ::Logging.log_internal {'growl notifications have been disabled'}
+      end
+    end
+
+    # call-seq:
+    #    map = { logging_levels => growl_levels }
+    #
+    # Configure the mapping from the Logging levels to the Growl
+    # notification levels. This is needed in order to log events at the
+    # proper Growl level.
+    #
+    # Without any configuration, the following maping will be used:
+    #
+    #    :debug  =>  -2
+    #    :info   =>  -1
+    #    :warn   =>  0
+    #    :error  =>  1
+    #    :fatal  =>  2
+    #
+    def map=( levels )
+      map = []
+      levels.keys.each do |lvl|
+        num = ::Logging.level_num(lvl)
+        map[num] = growl_level_num(levels[lvl])
+      end
+      @map = map
+    end
+
+
+    private
+
+    # call-seq:
+    #    write( event )
+    #
+    # Write the given _event_ to the growl notification facility. The log
+    # event will be processed through the Layout assciated with this
+    # appender. The message will be logged at the level specified by the
+    # event.
+    #
+    def write( event )
+      title = ''
+      priority = 0
+      message = if event.instance_of?(::Logging::LogEvent)
+          priority = @map[event.level]
+          @layout.format(event)
+        else
+          event.to_s
+        end
+      return if message.empty?
+
+      message = message.gsub(ColoredRegexp, '')
+      if @title_sep
+        title, message = message.split(@title_sep)
+        title, message = '', title if message.nil?
+      end
+
+      growl(title.strip, message.strip, priority)
+      self
+    end
+
+    # call-seq:
+    #    growl_level_num( level )    => integer
+    #
+    # Takes the given _level_ as a string or integer and returns the
+    # corresponding Growl notification level number.
+    #
+    def growl_level_num( level )
+      level = Integer(level)
+      if level < -2 or level > 2
+        raise ArgumentError, "level '#{level}' is not in range -2..2"
+      end
+      level
+    end
+
+    # call-seq:
+    #    growl( title, message, priority )
+    #
+    # Send the _message_ to the growl notifier using the given _title_ and
+    # _priority_.
+    #
+    def growl( title, message, priority )
+      message.tr!("`", "'")
+      if @coalesce then coalesce(title, message, priority)
+      else call_growl(title, message, priority) end
+    end
+
+    # call-seq:
+    #    coalesce( title, message, priority )
+    #
+    # Attempt to coalesce the given _message_ with any that might be pending
+    # in the queue to send to the growl notifier. Messages are coalesced
+    # with any in the queue that have the same _title_ and _priority_.
+    #
+    # There can be only one message in the queue, so if the _title_ and/or
+    # _priority_ don't match, the message in the queue is sent immediately
+    # to the growl notifier, and the current _message_ is queued.
+    #
+    def coalesce( *msg )
+      @c_mutex.synchronize do
+        if @c_queue.empty?
+          @c_queue << msg
+          @c_thread.run
+
+        else
+          qmsg = @c_queue.last
+          if qmsg.first != msg.first or qmsg.last != msg.last
+            @c_queue << msg
+          else 
+            qmsg[1] << "\n" << msg[1]
+          end
+        end
+      end
+
+      Thread.pass
+    end
+
+    # call-seq:
+    #    setup_coalescing
+    #
+    # Setup the appender to handle coalescing of messages before sending
+    # them to the growl notifier. This requires the creation of a thread and
+    # mutex for passing messages from the appender thread to the growl
+    # notifier thread.
+    #
+    def setup_coalescing
+      @c_mutex = Mutex.new
+      @c_queue = []
+
+      @c_thread = Thread.new do
+        Thread.stop
+        loop do
+          sleep 0.5
+          @c_mutex.synchronize {
+            call_growl(*@c_queue.shift) until @c_queue.empty?
+          }
+          Thread.stop if @c_queue.empty?
+        end  # loop
+      end  # Thread.new
+    end
+
+    # call-seq:
+    #    call_growl( title, message, priority )
+    #
+    # Call the growlnotify application with the given parameters. If the
+    # system call fails, the growl appender will be disabled.
+    #
+    def call_growl( *args )
+      unless system(@growl % args)
+        self.level = :off
+        ::Logging.log_internal {'growl notifications have been disabled'}
+      end
+    end
+
+  end  # class Growl
+end  # module Logging::Appenders
+
+# EOF