logging 0.9.8 → 1.0.0

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

@@ -0,0 +1,47 @@
+
+module Logging
+  module Layouts
+
+    # Accessor / Factory for the Basic layout.
+    #
+    def basic( *args )
+      return ::Logging::Layouts::Basic if args.empty?
+      ::Logging::Layouts::Basic.new(*args)
+    end
+
+    # Accessor / Factory for the Pattern layout.
+    #
+    def pattern( *args )
+      return ::Logging::Layouts::Pattern if args.empty?
+      ::Logging::Layouts::Pattern.new(*args)
+    end
+
+    # Accessor for the Parseable layout.
+    #
+    def parseable
+      ::Logging::Layouts::Parseable
+    end
+
+    # Factory for the Parseable layout using JSON formatting.
+    #
+    def json( *args )
+      ::Logging::Layouts::Parseable.json(*args)
+    end
+
+    # Factory for the Parseable layout using YAML formatting.
+    #
+    def yaml( *args )
+      ::Logging::Layouts::Parseable.yaml(*args)
+    end
+
+    extend self
+  end  # module Layouts
+end  # module Logging
+
+
+%w[basic parseable pattern].
+each do |fn|
+  require ::Logging.libpath('logging', 'layouts', fn)
+end
+
+# 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

data/lib/logging/layouts/pattern.rb

@@ -1,6 +1,5 @@
 
-module Logging
-module Layouts
+module Logging::Layouts
 
   # A flexible layout configurable with pattern string.
   #
@@ -22,7 +21,7 @@ module Layouts
   # Let the conversion pattern be "%-5l [%c]: %m\n" and assume that the
   # logging environment was set to use a Pattern layout. Then the statements
   #
-  #    root = Logging::Logger[:root]
+  #    root = Logging.logger[:root]
   #    root.debug("Message 1")
   #    root.warn("Message 2")
   #
@@ -57,9 +56,9 @@ module Layouts
   #  [t]  Used to output the object ID of the thread that generated the
   #       log event.
   #  [T]  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 options helps to create more human
-  #       readable output for multithread application log.
+  #       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.
   #  [%]  The sequence '%%' outputs a single percent sign.
   #
   # The directives F, L, and M will only work if the Logger generating the
@@ -290,7 +289,6 @@ module Layouts
     # :startdoc:
 
   end  # class Pattern
-end  # module Layouts
-end  # module Logging
+end  # module Logging::Layouts
 
 # EOF

data/lib/logging/log_event.rb

@@ -37,7 +37,7 @@ module Logging
 
         m = CALLER_RGXP.match(t)
         @file = m[1]
-        @line = m[2]
+        @line = Integer(m[2])
         @method = m[3] unless m[3].nil?
       end
     end

data/lib/logging/logger.rb

@@ -12,8 +12,8 @@ module Logging
   #
   # Example:
   #
-  #    log = Logging::Logger['my logger']
-  #    log.add_appenders( Logging::Appender.stdout )   # append to STDOUT
+  #    log = Logging.logger['my logger']
+  #    log.add_appenders( Logging.appenders.stdout )   # append to STDOUT
   #    log.level = :info                               # log 'info' and above
   #
   #    log.info 'starting foo operation'
@@ -312,8 +312,8 @@ module Logging
     #
     def add_appenders( *args )
       args.flatten.each do |arg|
-        o = arg.kind_of?(::Logging::Appender) ? arg : ::Logging::Appender[arg]
-        raise ArgumentError, "unknown appender '#{arg}'" if o.nil?
+        o = arg.kind_of?(::Logging::Appender) ? arg : ::Logging::Appenders[arg.to_s]
+        raise ArgumentError, "unknown appender #{arg.inspect}" if o.nil?
         @appenders << o unless @appenders.include?(o)
       end
       self

data/lib/spec/logging_helper.rb

@@ -11,7 +11,7 @@ module Spec
       to = opts.getopt(:to, '__rspec__')
       exclusive = opts.getopt(:exclusive, true)
 
-      appender = Logging::Appender[to] || Logging::Appenders::StringIo.new(to)
+      appender = Logging::Appenders[to] || Logging::Appenders::StringIo.new(to)
       logger = Logging::Logger[from]
       if exclusive
         logger.appenders = appender
@@ -20,7 +20,7 @@ module Spec
       end
 
       before(:all) do
-        @log_output = Logging::Appender[to]
+        @log_output = Logging::Appenders[to]
       end
 
       before(:each) do

data/test/appenders/test_buffered_io.rb

@@ -9,20 +9,18 @@ module TestAppenders
 
     def setup
       super
-      ::Logging.init
-      @levels = ::Logging::LEVELS
-
-      @appender = ::Logging::Appenders::StringIo.new(
+      @appender = Logging.appenders.string_io(
         'test_appender', :auto_flushing => 3, :immediate_at => :error
       )
+      @appender.clear
       @sio = @appender.sio
-
+      @levels = Logging::LEVELS
       begin readline rescue EOFError end
     end
 
     def test_append
-      event = ::Logging::LogEvent.new('TestLogger', @levels['warn'],
-                                      [1, 2, 3, 4], false)
+      event = Logging::LogEvent.new('TestLogger', @levels['warn'],
+                                    [1, 2, 3, 4], false)
       @appender.append event
       assert_nil(readline)
 
@@ -45,15 +43,15 @@ module TestAppenders
     def test_append_error
       # setup an internal logger to capture error messages from the IO
       # appender
-      log = Logging::Appenders::StringIo.new('__internal_io')
-      Logging::Logger[Logging].add_appenders(log)
-      Logging::Logger[Logging].level = 'all'
+      log = Logging.appenders.string_io('__internal_io')
+      Logging.logger[Logging].add_appenders(log)
+      Logging.logger[Logging].level = 'all'
 
 
       # close the string IO object so we get an error
       @sio.close
-      event = ::Logging::LogEvent.new('TestLogger', @levels['warn'],
-                                      [1, 2, 3, 4], false)
+      event = Logging::LogEvent.new('TestLogger', @levels['warn'],
+                                    [1, 2, 3, 4], false)
       @appender.append event
       assert_nil(log.readline)
 
@@ -68,6 +66,16 @@ module TestAppenders
       assert_equal 5, @appender.level
     end
 
+    def test_auto_flushing
+      assert_raise(ArgumentError) {
+        @appender.auto_flushing = Object.new
+      }
+
+      assert_raise(ArgumentError) {
+        @appender.auto_flushing = -1
+      }
+    end
+
     def test_close
       assert_equal false, @sio.closed?
       assert_equal false, @appender.closed?
@@ -77,7 +85,7 @@ module TestAppenders
       assert_equal true, @appender.closed?
 
       [STDIN, STDERR, STDOUT].each do |io|
-        @appender = ::Logging::Appenders::IO.new 'test', io
+        @appender = Logging.appenders.io('test', io)
         @appender.close
         assert_equal false, io.closed?
         assert_equal true, @appender.closed?
@@ -105,9 +113,9 @@ module TestAppenders
     def test_concat_error
       # setup an internal logger to capture error messages from the IO
       # appender
-      log = Logging::Appenders::StringIo.new('__internal_io')
-      Logging::Logger[Logging].add_appenders(log)
-      Logging::Logger[Logging].level = 'all'
+      log = Logging.appenders.string_io('__internal_io')
+      Logging.logger[Logging].add_appenders(log)
+      Logging.logger[Logging].level = 'all'
 
       # close the string IO object so we get an error
       @sio.close
@@ -141,8 +149,8 @@ module TestAppenders
     end
 
     def test_immediate_at
-      event = ::Logging::LogEvent.new('TestLogger', @levels['warn'],
-                                      [1, 2, 3, 4], false)
+      event = Logging::LogEvent.new('TestLogger', @levels['warn'],
+                                    [1, 2, 3, 4], false)
       @appender.append event
       assert_nil(readline)