logging 0.4.0 → 0.5.0

data/lib/logging/appenders/growl.rb

@@ -0,0 +1,206 @@
+# $Id: growl.rb 48 2007-11-18 21:47:29Z tim_pease $
+
+require 'logging/appender'
+
+module Logging
+module 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
+
+    # 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 -n '#{@name}' -t '%s' -m '%s' -p %d"
+
+      getopt = ::Logging.options(opts)
+      @coalesce = getopt[:coalesce, false]
+      @title_sep = getopt[:separator]
+
+      # provides a mapping from the default Logging levels
+      # to the Growl notification levels
+      @map = [-2, -1, 0, 1, 2]
+
+      map = getopt[:map]
+      self.map = map unless map.nil?
+
+      setup_coalescing if @coalesce
+    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
+
+    # call-seq:
+    #    append( event )
+    #
+    # Send the given _event_ to the Growl framework. 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 append( event )
+      if closed?
+        raise RuntimeError,
+              "appender '<#{self.class.name}: #{@name}>' is closed"
+      end
+
+      sync do
+        title = ''
+        message = @layout.format(event)
+        priority = @map[event.level]
+
+        if @title_sep
+          title, message = message.split(@title_sep)
+          title, message = message, title if message.nil?
+        end
+
+        growl(title, message, priority)
+      end unless @level > event.level
+      self
+    end
+
+    # call-seq:
+    #    syslog << string
+    #
+    # Write the given _string_ to the Growl framework "as is" -- no
+    # layout formatting will be performed. The string will be logged at the
+    # 0 notification level of the Growl framework.
+    #
+    def <<( str )
+      if closed?
+        raise RuntimeError,
+              "appender '<#{self.class.name}: #{@name}>' is closed"
+      end
+
+      title = ''
+      message = str
+
+      if @title_sep
+        title, message = message.split(@title_sep)
+        title, message = message, title if message.nil?
+      end
+
+      sync {growl(title, message, 0)}
+      self
+    end
+
+
+    private
+
+    # 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 = case level
+              when Integer: level
+              when String: Integer(level)
+              else raise ArgumentError, "unkonwn level '#{level}'" end
+      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 )
+      if @coalesce then coalesce(title, message, priority)
+      else system @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_message.nil? or @c_message.first != msg.first or @c_message.last  != msg.last
+          @c_message, msg = msg, @c_message
+          @c_thread.run
+
+        else
+          @c_message[1] << "\n" << msg[1]
+          msg = nil
+        end
+      end
+
+      system @growl % msg unless msg.nil?
+      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_message = nil
+
+      @c_thread = Thread.new do
+        loop do
+          Thread.stop
+          sleep 0.5
+          @c_mutex.synchronize do
+            break if @c_message.nil?
+            system @growl % @c_message
+            @c_message = nil
+          end
+        end   # loop
+      end   # Thread.new
+    end
+
+  end  # class Growl
+
+end  # module Appenders
+end  # module Logging
+
+# EOF

data/lib/logging/appenders/io.rb

@@ -1,17 +1,15 @@
-# $Id: io.rb 32 2007-02-22 23:32:17Z tim_pease $
+# $Id: io.rb 37 2007-10-26 19:12:44Z tim_pease $
 
 require 'logging/appender'
 
 module Logging
 module Appenders
 
-  #
   # This class provides an Appender that can write to any IO stream
   # configured for writing.
   #
   class IO < ::Logging::Appender
 
-    #
     # call-seq:
     #    IO.new( name, io )
     #    IO.new( name, io, :layout => layout )
@@ -29,7 +27,6 @@ module Appenders
       super(name, opts)
     end
 
-    #
     # call-seq:
     #    close( footer = true )
     #
@@ -46,7 +43,6 @@ module Appenders
       self
     end
 
-    #
     # call-seq:
     #    flush
     #
@@ -61,7 +57,7 @@ module Appenders
 
 
     private
-    #
+
     # call-seq:
     #    write( str )
     #

data/lib/logging/appenders/rolling_file.rb

@@ -1,10 +1,9 @@
-# $Id: rolling_file.rb 31 2007-02-22 23:16:17Z tim_pease $
+# $Id: rolling_file.rb 37 2007-10-26 19:12:44Z tim_pease $
 
 require 'logging/appenders/file'
 
 module Logging::Appenders
 
-  #
   # An appender that writes to a file and ensures that the file size or age
   # never exceeds some user specified level.
   #
@@ -31,7 +30,6 @@ module Logging::Appenders
   #
   class RollingFile < ::Logging::Appenders::File
 
-    #
     # call-seq:
     #    RollingFile.new( name, opts )
     #
@@ -139,8 +137,9 @@ module Logging::Appenders
       super(name, opts)
     end
 
+
     private
-    #
+
     # call-seq:
     #    write( str )
     #
@@ -154,7 +153,6 @@ module Logging::Appenders
       roll if roll_required?  # the file IO stream is probably not being 
     end                       # flushed to disk immediately
 
-    #
     # call-seq:
     #    roll
     #
@@ -167,7 +165,6 @@ module Logging::Appenders
       @io = ::File.new(@fn, 'a')
     end
 
-    #
     # call-seq:
     #    roll_required?
     #
@@ -184,7 +181,6 @@ module Logging::Appenders
       return sufficiently_aged?
     end
 
-    #
     # call-seq:
     #    roll_files
     #

data/lib/logging/appenders/static_appender.rb

@@ -1,4 +1,4 @@
-# $Id: static_appender.rb 26 2007-01-31 23:19:40Z tim_pease $
+# $Id: static_appender.rb 37 2007-10-26 19:12:44Z tim_pease $
 
 require 'logging/appenders/console'
 
@@ -9,7 +9,6 @@ class Appender
 
   class << self
 
-    #
     # call-seq:
     #    Appender[name]
     #
@@ -18,7 +17,6 @@ class Appender
     #
     def []( name ) @appenders[name] end
 
-    #
     # call-seq:
     #    Appender[name] = appender
     #
@@ -27,7 +25,6 @@ class Appender
     #
     def []=( name, val ) @appenders[name] = val end
 
-    #
     # call-seq:
     #    Appender.stdout
     #
@@ -39,7 +36,6 @@ class Appender
     #
     def stdout( ) self['stdout'] || ::Logging::Appenders::Stdout.new end
 
-    #
     # call-seq:
     #    Appender.stderr
     #

data/lib/logging/appenders/syslog.rb

@@ -0,0 +1,210 @@
+# $Id: syslog.rb 46 2007-10-31 14:39:01Z tim_pease $
+
+require 'logging/appender'
+require 'syslog'
+
+module Logging
+module Appenders
+
+  # This class provides an Appender that can write to the UNIX syslog
+  # daemon.
+  #
+  class Syslog < ::Logging::Appender
+    include ::Syslog::Constants
+
+    # call-seq:
+    #    Syslog.new( name, opts = {} )
+    #
+    # Create an appender that will log messages to the system message
+    # logger. The message is then written to the system console, log files,
+    # logged-in users, or forwarded to other machines as appropriate. The
+    # options that can be used to configure the appender are as follows:
+    #
+    #    :ident     => identifier string (name is used by default)
+    #    :logopt    => options used when opening the connection
+    #    :facility  => the syslog facility to use
+    #
+    # The parameter :ident is a string that will be prepended to every
+    # message. The :logopt argument is a bit field specifying logging
+    # options, which is formed by OR'ing one or more of the following
+    # values:
+    #
+    #    LOG_CONS      If syslog() cannot pass the message to syslogd(8) it
+    #                  wil attempt to write the message to the console
+    #                  ('/dev/console').
+    #
+    #    LOG_NDELAY    Open the connection to syslogd(8) immediately. Normally
+    #                  the open is delayed until the first message is logged.
+    #                  Useful for programs that need to manage the order in
+    #                  which file descriptors are allocated.
+    #
+    #    LOG_PERROR    Write the message to standard error output as well to
+    #                  the system log.
+    #
+    #    LOG_PID       Log the process id with each message: useful for
+    #                  identifying instantiations of daemons.
+    #
+    # The :facility parameter encodes a default facility to be assigned to
+    # all messages that do not have an explicit facility encoded:
+    #
+    #    LOG_AUTH      The authorization system: login(1), su(1), getty(8),
+    #                  etc.
+    #
+    #    LOG_AUTHPRIV  The same as LOG_AUTH, but logged to a file readable
+    #                  only by selected individuals.
+    #
+    #    LOG_CONSOLE   Messages written to /dev/console by the kernel console
+    #                  output driver.
+    #
+    #    LOG_CRON      The cron daemon: cron(8).
+    #
+    #    LOG_DAEMON    System daemons, such as routed(8), that are not
+    #                  provided for explicitly by other facilities.
+    #
+    #    LOG_FTP       The file transfer protocol daemons: ftpd(8), tftpd(8).
+    #
+    #    LOG_KERN      Messages generated by the kernel. These cannot be
+    #                  generated by any user processes.
+    #
+    #    LOG_LPR       The line printer spooling system: lpr(1), lpc(8),
+    #                  lpd(8), etc.
+    #
+    #    LOG_MAIL      The mail system.
+    #
+    #    LOG_NEWS      The network news system.
+    #
+    #    LOG_SECURITY  Security subsystems, such as ipfw(4).
+    #
+    #    LOG_SYSLOG    Messages generated internally by syslogd(8).
+    #
+    #    LOG_USER      Messages generated by random user processes. This is
+    #                  the default facility identifier if none is specified.
+    #
+    #    LOG_UUCP      The uucp system.
+    #
+    #    LOG_LOCAL0    Reserved for local use. Similarly for LOG_LOCAL1
+    #                  through LOG_LOCAL7.
+    #
+    def initialize( name, opts = {} )
+      super
+
+      ident = opts[:ident] || opts['ident'] || name
+      logopt = opts[:logopt] || opts['logopt'] || (LOG_PID | LOG_CONS)
+      facility = opts[:facility] || opts['facility'] || LOG_USER
+      @syslog = ::Syslog.open(ident, Integer(logopt), Integer(facility))
+
+      # provides a mapping from the default Logging levels
+      # to the syslog levels
+      @map = [LOG_DEBUG, LOG_INFO, LOG_WARNING, LOG_ERR, LOG_CRIT]
+
+      if opts.has_key?('map') or opts.has_key?(:map)
+        self.map = opts[:map] || opts['map']
+      end
+    end
+
+    # call-seq:
+    #    map = { logging_levels => syslog_levels }
+    #
+    # Configure the mapping from the Logging levels to the syslog levels.
+    # This is needed in order to log events at the proper syslog level.
+    #
+    # Without any configuration, the following maping will be used:
+    #
+    #    :debug  =>  LOG_DEBUG
+    #    :info   =>  LOG_INFO
+    #    :warn   =>  LOG_WARNING
+    #    :error  =>  LOG_ERR
+    #    :fatal  =>  LOG_CRIT
+    #
+    def map=( levels )
+      map = []
+      levels.keys.each do |lvl|
+        num = ::Logging.level_num(lvl)
+        map[num] = syslog_level_num(levels[lvl])
+      end
+      @map = map
+    end
+
+    # call-seq:
+    #    close
+    #
+    # Closes the connetion to the syslog facility.
+    #
+    def close
+      @syslog.close
+    end
+
+    # call-seq:
+    #    closed?    => true or false
+    #
+    # Queries the connection to the syslog facility and returns +true+ if
+    # the connection is closed.
+    #
+    def closed?
+      !@syslog.opened?
+    end
+
+    # call-seq:
+    #    append( event )
+    #
+    # Write the given _event_ to the syslog 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 append( event )
+      if closed?
+        raise RuntimeError,
+              "appender '<#{self.class.name}: #{@name}>' is closed"
+      end
+
+      sync do
+        msg = @layout.format(event)
+        pri = @map[event.level]
+        @syslog.log(pri, '%s', msg)
+      end unless @level > event.level
+      self
+    end
+
+    # call-seq:
+    #    syslog << string
+    #
+    # Write the given _string_ to the syslog facility "as is" -- no
+    # layout formatting will be performed. The string will be logged at the
+    # LOG_DEBUG level of the syslog facility.
+    #
+    def <<( str )
+      if closed?
+        raise RuntimeError,
+              "appender '<#{self.class.name}: #{@name}>' is closed"
+      end
+
+      sync {@syslog.log(LOG_DEBUG, '%s', str)}
+      self
+    end
+
+
+    private
+
+    # call-seq:
+    #    syslog_level_num( level )    => integer
+    #
+    # Takes the given _level_ as a string, symbol, or integer and returns
+    # the corresponding syslog level number.
+    #
+    def syslog_level_num( level )
+      case level
+      when Integer: level
+      when String, Symbol:
+        level = level.to_s.upcase
+        self.class.const_get level
+      else
+        raise ArgumentError, "unkonwn level '#{level}'"
+      end
+    end
+
+  end  # class Syslog
+
+end  # module Appenders
+end  # module Logging
+
+# EOF