TwP-logging 0.9.8 → 0.9.8.1

data/History.txt

@@ -1,7 +1,22 @@
+== 1.0.0 / 2009-04-17
+
+2 major enhancements
+  - Refactored access to the appenders
+  - Created a much cleaner way to initialize the logging framework
+3 minor enhancements
+  - Added a YAML layout option
+  - Added a JSON layout option
+  - Cration of an "examples" directory or logging configurations
+1 bug fix
+  - Logging initialization happens implicitly when a logger, layout, or
+    appender is created
+
 == 0.9.8 / 2009-04-11
 
-1 minor enhancement
+2 minor enhancements
   - Adding a to_s method to the StringIo appender's StringIO object
+  - Added a Spec::LoggingHelper class that will capture log messages
+    when using rspec style testing
 
 == 0.9.7 / 2009-03-17
 

data/Rakefile

@@ -25,7 +25,7 @@ PROJ.version = Logging::VERSION
 PROJ.readme_file = 'README.rdoc'
 PROJ.ignore_file = '.gitignore'
 
-PROJ.exclude << %w[^tags$]
+PROJ.exclude << %w[^tags$ logging.gemspec]
 PROJ.rdoc.exclude << '^data'
 #PROJ.rdoc.dir = 'doc/rdoc'
 #PROJ.rdoc.remote_dir = 'rdoc'

data/lib/logging/appender.rb

@@ -16,58 +16,6 @@ module Logging
 #
 class Appender
 
-  @appenders = Hash.new
-
-  class << self
-
-    # call-seq:
-    #    Appender[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:
-    #    Appender[name] = appender
-    #
-    # Stores the given _appender_ instance in the Appender hash under the
-    # key _name_.
-    #
-    def []=( name, val ) @appenders[name] = val 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:
-    #    Appender.stdout
-    #
-    # Returns an instance of the Stdout Appender. Unless the user explicitly
-    # creates a new Stdout Appender, the instance returned by this method
-    # will always be the same:
-    #
-    #    Appender.stdout.object_id == Appender.stdout.object_id    #=> true
-    #
-    def stdout( ) self['stdout'] || ::Logging::Appenders::Stdout.new end
-
-    # call-seq:
-    #    Appender.stderr
-    #
-    # Returns an instance of the Stderr Appender. Unless the user explicitly
-    # creates a new Stderr Appender, the instance returned by this method
-    # will always be the same:
-    #
-    #    Appender.stderr.object_id == Appender.stderr.object_id    #=> true
-    #
-    def stderr( ) self['stderr'] || ::Logging::Appenders::Stderr.new end
-
-  end  # class << self
-
   attr_reader :name, :layout, :level
 
   # call-seq:
@@ -85,6 +33,8 @@ class Appender
   #    :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
 
@@ -102,7 +52,7 @@ class Appender
       end
     end
 
-    ::Logging::Appender[@name] = self
+    ::Logging::Appenders[@name] = self
   end
 
   # call-seq:
@@ -217,7 +167,7 @@ class Appender
   #
   def close( footer = true )
     return self if @closed
-    ::Logging::Appender.remove(@name)
+    ::Logging::Appenders.remove(@name)
     @closed = true
 
     sync {flush}
@@ -298,6 +248,4 @@ class Appender
 end  # class Appender
 end  # module Logging
 
-Logging.require_all_libs_relative_to(__FILE__, 'appenders')
-
 # EOF

data/lib/logging/appenders/buffering.rb

@@ -117,8 +117,9 @@ module Logging::Appenders
     # options.
     #
     def configure_buffering( opts )
-      @buffer = []
+      ::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

data/lib/logging/appenders/console.rb

@@ -1,6 +1,4 @@
 
-require Logging.libpath(*%w[logging appenders io])
-
 module Logging::Appenders
 
   # This class provides an Appender that can write to STDOUT.

data/lib/logging/appenders/rolling_file.rb

@@ -1,6 +1,4 @@
 
-require 'lockfile'
-
 module Logging::Appenders
 
   # An appender that writes to a file and ensures that the file size or age

data/lib/logging/appenders/string_io.rb

@@ -1,6 +1,4 @@
 
-require 'stringio'
-
 module Logging::Appenders
 
   # This class provides an Appender that can write to a StringIO instance.
@@ -20,24 +18,8 @@ module Logging::Appenders
     def initialize( name, opts = {} )
       @sio = StringIO.new
       @sio.extend IoToS
+      @pos = 0
       super(name, @sio, opts)
-      clear
-    end
-
-    # Read a single line of text from the internal StringIO instance. +nil+
-    # is returned if the StringIO buffer is empty.
-    #
-    def readline
-      sync {
-        begin
-          @sio.seek @pos
-          line = @sio.readline
-          @pos = @sio.tell
-          line
-        rescue EOFError
-          nil
-        end
-      }
     end
 
     # Clears the internal StringIO instance. All log messages are removed
@@ -52,6 +34,23 @@ module Logging::Appenders
     end
     alias :reset :clear
 
+    %w[read readline readlines].each do|m|
+      class_eval <<-CODE
+        def #{m}( *args )
+          sync {
+            begin
+              @sio.seek @pos
+              rv = @sio.#{m}(*args)
+              @pos = @sio.tell
+              rv
+            rescue EOFError
+              nil
+            end
+          }
+        end
+      CODE
+    end
+
     # :stopdoc:
     module IoToS
       def to_s

data/lib/logging/appenders/syslog.rb

@@ -1,11 +1,4 @@
 
-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
 #

data/lib/logging/appenders.rb

@@ -0,0 +1,120 @@
+
+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)
+      nil
+    end
+
+    extend self
+    @appenders = Hash.new
+
+  end  # module Appenders
+end  # module Logging
+
+
+%w[buffering io console email file growl rolling_file string_io syslog].
+each do |fn|
+  require ::Logging.libpath('logging', 'appenders', fn)
+end
+
+# EOF

data/lib/logging/config/configurator.rb

@@ -82,7 +82,7 @@ module Logging::Config
         l.additive  = config[:additive] if l.respond_to? :additive= 
         l.trace     = config[:trace]
         l.appenders = Array(config[:appenders]).
-                            map {|name| ::Logging::Appender[name]}
+                            map {|nm| ::Logging::Appenders[nm]}
       end
     end
 

data/lib/logging/config/yaml_configurator.rb

@@ -1,8 +1,5 @@
 
-require 'yaml'
-
-module Logging
-module Config
+module Logging::Config
 
   # The YamlConfigurator class is used to configure the Logging framework
   # using information found in a YAML file.
@@ -137,7 +134,7 @@ module Config
         l.trace = config['trace'] if l.respond_to? :trace=
 
         if config.has_key?('appenders')
-          l.appenders = config['appenders'].map {|n| ::Logging::Appender[n]}
+          l.appenders = config['appenders'].map {|n| ::Logging::Appenders[n]}
         end
       end
     end
@@ -189,7 +186,6 @@ module Config
     end
 
   end  # class YamlConfigurator
-end  # module Config
-end  # module Logging
+end  # module Logging::Config
 
 # EOF

data/lib/logging/layout.rb

@@ -1,6 +1,4 @@
  
-require 'yaml'
-
 module Logging
 
 # The +Layout+ class provides methods for formatting log events into a
@@ -30,6 +28,8 @@ class Layout
   # then <tt>:string</tt> is used.
   #
   def initialize( opts = {} )
+    ::Logging.init unless ::Logging.const_defined? :MAX_LEVEL_LENGTH
+
     default = ::Logging.const_defined?('OBJ_FORMAT') ?
               ::Logging::OBJ_FORMAT : nil
 
@@ -114,6 +114,4 @@ class Layout
 end  # class Layout
 end  # module Logging
 
-Logging.require_all_libs_relative_to(__FILE__, 'layouts')
-
 # EOF

data/lib/logging/layouts/basic.rb

@@ -1,6 +1,5 @@
 
-module Logging
-module Layouts
+module Logging::Layouts
 
   # The +Basic+ layout class provides methods for simple formatting of log
   # events. The resulting string follows the format below.
@@ -28,7 +27,6 @@ module Layouts
     end
 
   end  # class Basic
-end  # module Layouts
-end  # module Logging
+end  # module Logging::Layouts
 
 # EOF

data/lib/logging/layouts/parseable.rb

@@ -0,0 +1,211 @@
+
+module Logging::Layouts
+
+  # This layout will produce parseable log output in either JSON or YAML
+  # format. This makes it much easier for machines to parse log files and
+  # perform analysis on those logs.
+  #
+  # The information about the log event can be configured when the layout is
+  # created. Any or all of the following labels can be set as the _items_ to
+  # log:
+  #
+  #   'logger'     Used to output the name of the logger that generated the
+  #                log event.
+  #   'timestamp'  Used to output the timestamp of the log event.
+  #   'level'      Used to output the level of the log event.
+  #   'message'    Used to output the application supplied message
+  #                associated with the log event.
+  #   'file'       Used to output the file name where the logging request
+  #                was issued.
+  #   'line'       Used to output the line number where the logging request
+  #                was issued.
+  #   'method'     Used to output the method name where the logging request
+  #                was issued.
+  #   'pid'        Used to output the process ID of the currently running
+  #                program.
+  #   'millis'     Used to output the number of milliseconds elapsed from
+  #                the construction of the Layout until creation of the log
+  #                event.
+  #   'thread_id'  Used to output the object ID of the thread that generated
+  #                the log event.
+  #   'thread'     Used to output the name of the thread that generated the
+  #                log event. Name can be specified using Thread.current[:name]
+  #                notation. Output empty string if name not specified. This
+  #                option helps to create more human readable output for
+  #                multithread application logs.
+  #
+  # These items are supplied to the layout as an array of strings. The items
+  # 'file', 'line', and 'method' will only work if the Logger generating the
+  # events is configured to generate tracing information. If this is not the
+  # case these fields will always be empty.
+  #
+  # When configured to output log events in YAML format, each log message
+  # will be formatted as a hash in it's own YAML document. The hash keys are
+  # the name of the item, and the value is what you would expect it to be.
+  # Therefore, for the default set of times log message would appear as
+  # follows:
+  #
+  #   ---
+  #   timestamp: 2009-04-17 16:15:42
+  #   level: INFO
+  #   logger: Foo::Bar
+  #   message: this is a log message
+  #   ---
+  #   timestamp: 2009-04-17 16:15:43
+  #   level: ERROR
+  #   logger: Foo
+  #   message: <RuntimeError> Oooops!!
+  #
+  # The output order of the fields is not guaranteed to be the same as the
+  # order specified in the _items_ list. This is because Ruby hashes are not
+  # ordered by default (unless your running this in Ruby 1.9).
+  #
+  # When configured to output log events in JSON format, each log message
+  # will be formatted as an object (in the JSON sense of the work) on it's
+  # own line in the log output. Therefore, to parse the output you must read
+  # it line by line and parse the individual objects. Taking the same
+  # example above the JSON output would be:
+  # 
+  #   {"timestamp":"2009-04-17 16:15:42","level":"INFO","logger":"Foo::Bar","message":"this is a log message"}
+  #   {"timestamp":"2009-04-17 16:15:43","level":"ERROR","logger":"Foo","message":"<RuntimeError> Oooops!!"}
+  #
+  # The output order of the fields is guaranteed to be the same as the order
+  # specified in the _items_ list.
+  #
+  class Parseable < ::Logging::Layout
+
+    # :stopdoc:
+    # Arguments to sprintf keyed to directive letters
+    DIRECTIVE_TABLE = {
+      'logger'    => 'event.logger',
+      'timestamp' => 'Time.now.strftime(Pattern::ISO8601)',
+      'level'     => '::Logging::LNAMES[event.level]',
+      'message'   => 'format_obj(event.data)',
+      'file'      => 'event.file',
+      'line'      => 'event.line',
+      'method'    => 'event.method',
+      'pid'       => 'Process.pid',
+      'millis'    => 'Integer((Time.now-@created_at)*1000)',
+      'thread_id' => 'Thread.current.object_id',
+      'thread'    => 'Thread.current[:name]'
+    }
+
+    # call-seq:
+    #    Pattern.create_yaml_format_methods( layout )
+    #
+    # This method will create the +format+ method in the given Parseable
+    # _layout_ based on the configured items for the layout instance.
+    #
+    def self.create_yaml_format_method( layout )
+      code = "undef :format if method_defined? :format\n"
+      code << "def format( event )\nstr = {\n"
+
+      code << layout.items.map {|name|
+        "'#{name}' => #{Parseable::DIRECTIVE_TABLE[name]}"
+      }.join(",\n")
+      code << "\n}.to_yaml\nreturn str\nend\n"
+
+      (class << layout; self end).class_eval(code, __FILE__, __LINE__)
+    end
+
+    # call-seq:
+    #    Pattern.create_json_format_methods( layout )
+    #
+    # This method will create the +format+ method in the given Parseable
+    # _layout_ based on the configured items for the layout instance.
+    #
+    def self.create_json_format_method( layout )
+      code = "undef :format if method_defined? :format\n"
+      code << "def format( event )\n\"{"
+
+      args = []
+      code << layout.items.map {|name|
+        args << "format_as_json(#{Parseable::DIRECTIVE_TABLE[name]})"
+        "\\\"#{name}\\\":%s"
+      }.join(',')
+      code << "}\\n\" % [#{args.join(', ')}]\nend"
+      
+      (class << layout; self end).class_eval(code, __FILE__, __LINE__)
+    end
+    # :startdoc:
+
+    # call-seq:
+    #    Parseable.json( opts )
+    #
+    # Create a new Parseable layout that outputs log events usig JSON style
+    # formatting. See the initializer documentation for available options.
+    #
+    def self.json( opts = {} )
+      opts[:style] = 'json'
+      new(opts)
+    end
+
+    # call-seq:
+    #    Parseable.yaml( opts )
+    #
+    # Create a new Parseable layout that outputs log events usig YAML style
+    # formatting. See the initializer documentation for available options.
+    #
+    def self.yaml( opts = {} )
+      opts[:style] = 'yaml'
+      new(opts)
+    end
+
+    # call-seq:
+    #    Parseable.new( opts )
+    #
+    # Creates a new Parseable layout using the following options:
+    #
+    #    :style  => :json or :yaml
+    #    :items  => %w[timestamp level logger message]
+    #
+    def initialize( opts = {} )
+      super
+      @created_at = Time.now
+      @style = opts.getopt(:style, 'json').to_s.intern
+      self.items = opts.getopt(:items, %w[timestamp level logger message])
+    end
+
+    attr_reader :items
+
+    # call-seq:
+    #    layout.items = %w[timestamp level logger message]
+    #
+    # Set the log event items that will be formatted by this layout. These
+    # items, and only these items, will appear in the log output.
+    #
+    def items=( ary )
+      @items = Array(ary).map {|name| name.to_s.downcase}
+      valid = DIRECTIVE_TABLE.keys
+      @items.each do |name|
+        raise ArgumentError, "unknown item - #{name.inspect}" unless valid.include? name
+      end
+      create_format_method
+    end
+
+
+    private
+
+    # Take the given _value_ and format it into a JSON compatible string.
+    #
+    def format_as_json( value )
+      case value
+      when String, Integer, Float; value.inspect
+      when nil; 'null'
+      else value.to_s.inspect end
+    end
+
+    # Call the appropriate class level create format method based on the
+    # style of this parseable layout.
+    #
+    def create_format_method
+      case @style
+      when :json; Parseable.create_json_format_method(self)
+      when :yaml; Parseable.create_yaml_format_method(self)
+      else raise ArgumentError, "unknown format style '#@style'" end
+    end
+
+  end  # class Parseable
+end  # module Logging::Layouts
+
+# EOF