filterfish-logging 0.9.8

data/lib/logging/appenders/syslog.rb

@@ -0,0 +1,202 @@
+# $Id$
+
+begin
+  require 'syslog'
+  HAVE_SYSLOG = true
+rescue LoadError
+  HAVE_SYSLOG = false
+end
+
+# only load this class if we have the syslog library
+# Windows does not have syslog
+#
+if HAVE_SYSLOG
+
+module Logging::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 = {} )
+      ident = opts.getopt(:ident, name)
+      logopt = opts.getopt(:logopt, (LOG_PID | LOG_CONS), :as => Integer)
+      facility = opts.getopt(:facility, LOG_USER, :as => Integer)
+      @syslog = ::Syslog.open(ident, logopt, facility)
+
+      # provides a mapping from the default Logging levels
+      # to the syslog levels
+      @map = [LOG_DEBUG, LOG_INFO, LOG_WARNING, LOG_ERR, LOG_CRIT]
+
+      map = opts.getopt(:map)
+      self.map = map unless map.nil?
+
+      super
+    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( footer = true )
+      super
+      @syslog.close
+      self
+    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
+
+
+    private
+
+    # call-seq:
+    #    write( 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 write( event )
+      pri = LOG_DEBUG
+      message = if event.instance_of?(::Logging::LogEvent)
+          pri = @map[event.level]
+          @layout.format(event)
+        else
+          event.to_s
+        end
+      return if message.empty?
+
+      @syslog.log(pri, '%s', message)
+      self
+    end
+
+    # 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 Logging::Appenders
+end  # HAVE_SYSLOG
+
+# EOF

data/lib/logging/config/yaml_configurator.rb

@@ -0,0 +1,197 @@
+# $Id$
+
+require 'yaml'
+
+module Logging
+module Config
+
+  # The YamlConfigurator class is used to configure the Logging framework
+  # using information found in a YAML file.
+  #
+  class YamlConfigurator
+
+    class Error < StandardError; end  # :nodoc:
+
+    class << self
+
+      # call-seq:
+      #    YamlConfigurator.load( file, key = 'logging_config' )
+      #
+      # Load the given YAML _file_ and use it to configure the Logging
+      # framework. The file can be either a filename, and open File, or an
+      # IO object. If it is the latter two, the File / IO object will not be
+      # closed by this method.
+      #
+      # The configuration will be loaded from the given _key_ in the YAML
+      # stream.
+      #
+      def load( file, key = 'logging_config' )
+        io, close = nil, false
+        case file
+        when String
+          ext = File.extname(file)
+          if ext == 'yml' || ext == 'yaml'
+            io = File.open(file, 'r')
+            close = true
+          else
+            io = StringIO.new(file)
+            close = true
+          end
+        when IO
+          io = file
+        else
+          raise Error, 'expecting a filename or a File'
+        end
+
+        begin
+          new(io, key).load
+        ensure
+          io.close if close
+        end
+        nil
+      end
+    end  # class << self
+
+    # call-seq:
+    #    YamlConfigurator.new( io, key )
+    #
+    # Creates a new YAML configurator that will load the Logging
+    # configuration from the given _io_ stream. The configuration will be
+    # loaded from the given _key_ in the YAML stream.
+    #
+    def initialize( io, key  )
+      YAML.load_documents(io) do |doc|
+        @config = doc[key]
+        break if @config.instance_of?(Hash)
+      end
+
+      unless @config.instance_of?(Hash)
+        raise Error, "Key '#{key}' not defined in YAML configuration"
+      end
+    end
+
+    # call-seq:
+    #    load
+    #
+    # Loads the Logging configuration from the data loaded from the YAML
+    # file.
+    #
+    def load
+      pre_config @config['pre_config']
+      appenders @config['appenders']
+      loggers @config['loggers']
+    end
+
+    # call-seq:
+    #    pre_config( config )
+    #
+    # Configures the logging levels, object format style, and root logging
+    # level.
+    #
+    def pre_config( config )
+      # if no pre_config section was given, just create an empty hash
+      # we do this to ensure that some logging levels are always defined
+      config ||= Hash.new
+
+      # define levels
+      levels = config['define_levels']
+      ::Logging.init(levels) unless levels.nil?
+
+      # format as
+      format = config['format_as']
+      ::Logging.format_as(format) unless format.nil?
+
+      # grab the root logger and set the logging level
+      root = ::Logging::Logger.root
+      if config.has_key?('root')
+        root.level = config['root']['level']
+      end
+    end
+
+    # call-seq:
+    #    appenders( ary )
+    #
+    # Given an array of Appender configurations, this method will iterate
+    # over each and create the Appender(s).
+    #
+    def appenders( ary )
+      return if ary.nil?
+
+      ary.each {|h| appender(h)}
+    end
+
+    # call-seq:
+    #    loggers( ary )
+    #
+    # Given an array of Logger configurations, this method will iterate over
+    # each and create the Logger(s).
+    #
+    def loggers( ary )
+      return if ary.nil?
+
+      ary.each do |config|
+        name = config['name']
+        raise Error, 'Logger name not given' if name.nil?
+
+        l = Logging::Logger.new name
+        l.level = config['level'] if config.has_key?('level')
+        l.additive = config['additive'] if l.respond_to? :additive=
+        l.trace = config['trace'] if l.respond_to? :trace=
+
+        if config.has_key?('appenders')
+          l.appenders = config['appenders'].map {|n| ::Logging::Appender[n]}
+        end
+      end
+    end
+
+    # call-seq:
+    #    appender( config )
+    #
+    # Creates a new Appender based on the given _config_ options (a hash).
+    # The type of Appender created is determined by the 'type' option in the
+    # config. The remaining config options are passed to the Appender
+    # initializer.
+    #
+    # The config options can also contain a 'layout' option. This should be
+    # another set of options used to create a Layout for this Appender.
+    #
+    def appender( config )
+      return if config.nil?
+      config = config.dup
+
+      type = config.delete('type')
+      raise Error, 'Appender type not given' if type.nil?
+
+      name = config.delete('name')
+      raise Error, 'Appender name not given' if type.nil?
+
+      config['layout'] = layout(config.delete('layout'))
+
+      clazz = ::Logging::Appenders.const_get type
+      clazz.new(name, config)
+    end
+
+    # call-seq:
+    #    layout( config )
+    #
+    # Creates a new Layout based on the given _config_ options (a hash).
+    # The type of Layout created is determined by the 'type' option in the
+    # config. The remaining config options are passed to the Layout
+    # initializer.
+    #
+    def layout( config )
+      return if config.nil?
+      config = config.dup
+
+      type = config.delete('type')
+      raise Error, 'Layout type not given' if type.nil?
+
+      clazz = ::Logging::Layouts.const_get type
+      clazz.new config
+    end
+
+  end  # class YamlConfigurator
+end  # module Config
+end  # module Logging
+
+# EOF

data/lib/logging/layout.rb

@@ -0,0 +1,103 @@
+# $Id$
+ 
+require 'yaml'
+
+module Logging
+
+# The +Layout+ class provides methods for formatting log events into a
+# string representation. Layouts are used by Appenders to format log
+# events before writing them to the logging destination.
+#
+# All other Layouts inherit from this class which provides stub methods.
+# Each subclass should provide a +format+ method. A layout can be used by
+# more than one +Appender+ so all the methods need to be thread safe.
+#
+class Layout
+
+  # call-seq:
+  #    Layout.new( :format_as => :string )
+  #
+  # Creates a new layout that will format objecs as strings using the
+  # given <tt>:format_as</tt> style. This can be one of <tt>:string</tt>,
+  # <tt>:inspect</tt>, or <tt>:yaml</tt>. These formatting commands map to
+  # the following object methods:
+  #
+  # * :string  => to_s
+  # * :inspect => inspect
+  # * :yaml    => to_yaml
+  #
+  # If the format is not specified then the global object format is used
+  # (see Logging#format_as). If the global object format is not specified
+  # then <tt>:string</tt> is used.
+  #
+  def initialize( opts = {} )
+    default = ::Logging.const_defined?('OBJ_FORMAT') ?
+              ::Logging::OBJ_FORMAT : nil
+
+    f = opts.getopt(:format_as, default)
+    f = f.intern if f.instance_of? String
+
+    @obj_format = case f
+                  when :inspect, :yaml; f
+                  else :string end
+  end
+
+  # call-seq:
+  #    format( event )
+  #
+  # Returns a string representation of the given loggging _event_. It is
+  # up to subclasses to implement this method.
+  #
+  def format( event ) nil end
+
+  # call-seq:
+  #    header
+  #
+  # Returns a header string to be used at the beginning of a logging
+  # appender.
+  #
+  def header( ) '' end
+
+  # call-seq:
+  #    footer
+  #
+  # Returns a footer string to be used at the end of a logging appender.
+  #
+  def footer( ) '' end 
+
+
+  protected
+
+  # call-seq:
+  #    format_obj( obj )
+  #
+  # Return a string representation of the given object. Depending upon
+  # the configuration of the logger system the format will be an +inspect+
+  # based represenation or a +yaml+ based representation.
+  #
+  def format_obj( obj )
+    case obj
+    when String; obj
+    when Exception 
+      str = "<#{obj.class.name}> #{obj.message}"
+      unless obj.backtrace.nil?
+        str << "\n\t" << obj.backtrace.join("\n\t")
+      end
+      str
+    when nil; "<#{obj.class.name}> nil"
+    else
+      str = "<#{obj.class.name}> "
+      str << case @obj_format
+             when :inspect; obj.inspect
+             when :yaml; "\n#{obj.to_yaml}"
+             else obj.to_s end
+      str
+    end
+  end
+
+end  # class Layout
+end  # module Logging
+
+Logging.require_all_libs_relative_to(__FILE__, 'layouts')
+
+# EOF