logging 1.0.0 → 1.1.0

data/History.txt

@@ -1,3 +1,11 @@
+== 1.1.0 / 2009-04-21
+
+3 minor enhancements
+  - Added a "global" logger method
+  - Loggers can be consolidated on a per-namespace basis
+  - Added a precision to the logger name specifier in the pattern layout
+    [addresses http://github.com/TwP/logging/issues#issue/1]
+
 == 1.0.0 / 2009-04-17
 
 2 major enhancements

data/README.rdoc

@@ -86,6 +86,7 @@ package. The recommended reading order is the following:
   appenders.rb
   layouts.rb
   formatting.rb
+  consolidation.rb
 
 == NOTES
 

data/examples/consolidation.rb

@@ -0,0 +1,81 @@
+#
+# Logging support can be included globally giving all objects in the Ruby
+# space access to a logger instance. This "logger" method invokes
+#
+#    Logging.logger[self]
+#
+# And returns the appropriate logger for the current context.
+#
+# However, there might be times when it is not desirable to create an
+# individual logger for every class and module. This is where the concept of
+# "logger consolidation" comes into play. A ruby namespace can be configured
+# to consolidate loggers such that all classes and modules in that namespace
+# use the same logger instance.
+#
+# Because our loggers are being accessed via the self context, it becomes
+# very easy to turn on debugging on a class-by-class basis (or a
+# module-by-module basis). The trick is to create the debug logger first and
+# then configure the namespace to consolidate all loggers. Since we already
+# created our debug logger, it will be used by the class in question instead
+# of the consolidated namespace logger.
+#
+
+  require 'logging'
+  include Logging.globally
+
+  Logging.logger.root.appenders = Logging.appenders.stdout
+  Logging.logger.root.level = :info
+
+  # we want to debug the "FooBar" module of ActiveRecord
+  Logging.logger['ActiveRecord::FooBar'].level = :debug
+
+  # and we want everything else in ActiveRecord and ActiveResource
+  # to use the same consolidated loggers (one for each namespace)
+  Logging.consolidate 'ActiveRecord', 'ActiveResource'
+
+
+  logger.info 'because we included Logging globally, ' \
+              'we have access to a logger anywhere in our code'
+
+
+  module ActiveRecord
+    logger.info 'even at the module level'
+
+    class Base
+      logger.info 'and at the class level'
+    end
+  end
+
+
+  module ActiveResource
+    logger.info "you'll notice that these log messages " \
+                "are coming from the same logger"
+
+    class Base
+      logger.info "even though the logger is invoked from different classes"
+    end
+
+    class Foo
+      def foo
+        logger.info "that is because ActiveRecord and ActiveResource " \
+                    "are consolidating loggers in their respective namespaces"
+      end
+    end
+    Foo.new.foo
+  end
+
+
+  module ActiveRecord
+    logger.debug 'this debug message will not be logged ' \
+                 '- level is info'
+
+    class Base
+      logger.debug 'and this debug message will not be logged either ' \
+                   '- same logger as above'
+    end
+
+    module FooBar
+      logger.debug 'however, this debug message WILL be logged'
+    end
+  end
+

data/lib/logging.rb

@@ -30,7 +30,7 @@ begin require 'fastthread'; rescue LoadError; end
 module Logging
 
   # :stopdoc:
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
   LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
   PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
   WIN32 = %r/djgpp|(cyg|ms|bcc)win|mingw/ =~ RUBY_PLATFORM
@@ -172,6 +172,67 @@ module Logging
       ::Logging::Appenders
     end
 
+    # call-seq:
+    #    Logging.consolidate( 'First::Name', 'Second::Name', ... )
+    #
+    # Consolidate all loggers under the given namespace. All child loggers
+    # in the namespace will use the "consolidated" namespace logger instead
+    # of creating a new logger for each class or module.
+    #
+    # If the "root" logger name is passed to this method then all loggers
+    # will consolidate to the root logger. In other words, only the root
+    # logger will be created, and it will be used by all classes and moduels
+    # in the applicaiton.
+    #
+    # ==== Example
+    #
+    #    Logging.consolidate( 'Foo' )
+    #
+    #    foo = Logging.logger['Foo']
+    #    bar = Logging.logger['Foo::Bar']
+    #    baz = Logging.logger['Baz']
+    #
+    #    foo.object_id == bar.object_id    #=> true
+    #    foo.object_id == baz.object_id    #=> false
+    #
+    def consolidate( *args )
+      ::Logging::Repository.instance.add_master(*args)
+    end
+
+    # call-seq:
+    #    include Logging.globally
+    #    include Logging.globally( :logger )
+    #
+    # Add a "logger" method to the including context. If included from
+    # Object or Kernel, the logger method will be available to all objects.
+    #
+    # Optionally, a method name can be given and that will be used to
+    # provided access to the logger:
+    #
+    #    include Logging.globally( :log )
+    #    log.info "Just using a shorter method name"
+    #
+    # If you prefer to use the shorter "log" to access the logger.
+    #
+    # ==== Example
+    #
+    #   include Logging.globally
+    #
+    #   class Foo
+    #     logger.debug "Loading the Foo class"
+    #     def initialize
+    #       logger.info "Creating some new foo"
+    #     end
+    #   end
+    #
+    #   logger.fatal "End of example"
+    #
+    def globally( name = :logger )
+      Module.new {
+        eval "def #{name}() @_logging_logger ||= ::Logging::Logger[self] end"
+      }
+    end
+
     # call-seq:
     #    Logging.init( levels )
     #

data/lib/logging/layouts/pattern.rb

@@ -38,7 +38,7 @@ module Logging::Layouts
   # conversion characters are 
   #
   #  [c]  Used to output the name of the logger that generated the log
-  #       event.
+  #       event. Supports an optional "precision" described further below.
   #  [d]  Used to output the date of the log event. The format of the
   #       date is specified using the :date_pattern option when the Layout
   #       is created. ISO8601 format is assumed if not date pattern is given.
@@ -61,6 +61,11 @@ module Logging::Layouts
   #       more human readable output for multithread application logs.
   #  [%]  The sequence '%%' outputs a single percent sign.
   #
+  # The logger name directive 'c' accepts an optional precision that will
+  # only print the rightmost number of namespace identifiers for the logger.
+  # By default the logger name is printed in full. For example, for the
+  # logger name "Foo::Bar::Baz" the pattern %c{2} will output "Bar::Baz".
+  #
   # The directives F, L, and M 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.
@@ -118,30 +123,31 @@ module Logging::Layouts
 
     # Arguments to sprintf keyed to directive letters
     DIRECTIVE_TABLE = {
-      'c' => 'event.logger',
-      'd' => 'format_date',
-      'F' => 'event.file',
-      'l' => '::Logging::LNAMES[event.level]',
-      'L' => 'event.line',
-      'm' => 'format_obj(event.data)',
-      'M' => 'event.method',
-      'p' => 'Process.pid',
-      'r' => 'Integer((Time.now-@created_at)*1000).to_s',
-      't' => 'Thread.current.object_id.to_s',
-      'T' => 'Thread.current[:name]',
+      'c' => 'event.logger'.freeze,
+      'd' => 'format_date'.freeze,
+      'F' => 'event.file'.freeze,
+      'l' => '::Logging::LNAMES[event.level]'.freeze,
+      'L' => 'event.line'.freeze,
+      'm' => 'format_obj(event.data)'.freeze,
+      'M' => 'event.method'.freeze,
+      'p' => 'Process.pid'.freeze,
+      'r' => 'Integer((Time.now-@created_at)*1000).to_s'.freeze,
+      't' => 'Thread.current.object_id.to_s'.freeze,
+      'T' => 'Thread.current[:name]'.freeze,
       '%' => :placeholder
-    }
+    }.freeze
 
     # Matches the first directive encountered and the stuff around it.
     #
     # * $1 is the stuff before directive or "" if not applicable
     # * $2 is the %#.# match within directive group
     # * $3 is the directive letter
-    # * $4 is the stuff after the directive or "" if not applicable
-    DIRECTIVE_RGXP = %r/([^%]*)(?:(%-?\d*(?:\.\d+)?)([a-zA-Z%]))?(.*)/m
+    # * $4 is the precision specifier for the logger name
+    # * $5 is the stuff after the directive or "" if not applicable
+    DIRECTIVE_RGXP = %r/([^%]*)(?:(%-?\d*(?:\.\d+)?)([a-zA-Z%])(?:\{(\d+)\})?)?(.*)/m
 
     # default date format
-    ISO8601 = "%Y-%m-%d %H:%M:%S"
+    ISO8601 = "%Y-%m-%d %H:%M:%S".freeze
 
     # call-seq:
     #    Pattern.create_date_format_methods( pf )
@@ -167,6 +173,7 @@ module Logging::Layouts
         code << "Time.now.#{pf.date_method}\n"
       end
       code << "end\n"
+      ::Logging.log_internal(0) {code}
 
       pf._meta_eval(code, __FILE__, __LINE__)
     end
@@ -191,22 +198,33 @@ module Logging::Layouts
 
         case m[3]
         when '%'; code << '%%'
+        when 'c' 
+          code << m[2] + 's'
+          args << DIRECTIVE_TABLE[m[3]].dup
+          if m[4]
+            raise ArgumentError, "logger name precision must be an integer greater than zero: #{m[4]}" unless Integer(m[4]) > 0
+            args.last <<
+                ".split(::Logging::Repository::PATH_DELIMITER)" \
+                ".last(#{m[4]}).join(::Logging::Repository::PATH_DELIMITER)"
+          end
         when *DIRECTIVE_TABLE.keys
           code << m[2] + 's'
+          code << "{#{m[4]}}" if m[4]
           args << DIRECTIVE_TABLE[m[3]]
         when nil; break
         else
           raise ArgumentError, "illegal format character - '#{m[3]}'"
         end
 
-        break if m[4].empty?
-        pattern = m[4]
+        break if m[5].empty?
+        pattern = m[5]
       end
 
       code << '"'
       code << ', ' + args.join(', ') unless args.empty?
       code << ")\n"
       code << "end\n"
+      ::Logging.log_internal(0) {code}
 
       pf._meta_eval(code, __FILE__, __LINE__)
     end

data/lib/logging/logger.rb

@@ -51,9 +51,22 @@ module Logging
         @mutex.synchronize do
           logger = repo[name]
           if logger.nil?
-            logger = super(name, *args)
-            repo[name] = logger
-            repo.children(name).each {|c| c.__send__(:parent=, logger)}
+
+            master = repo.master_for(name)
+            if master
+              if repo.has_logger?(master)
+                logger = repo[master]
+              else
+                logger = super(master)
+                repo[master] = logger
+                repo.children(master).each {|c| c.__send__(:parent=, logger)}
+              end
+              repo[name] = logger
+            else
+              logger = super(name)
+              repo[name] = logger
+              repo.children(name).each {|c| c.__send__(:parent=, logger)}
+            end
           end
           logger
         end

data/lib/logging/repository.rb

@@ -18,6 +18,7 @@ module Logging
     # +Repository+ instance.
     #
     def initialize
+      @masters = []
       @h = {:root => ::Logging::RootLogger.new}
 
       # configures the internal logger which is disabled by default
@@ -107,7 +108,7 @@ module Logging
     # of B is A. Parents are determined by namespace.
     #
     def parent( key )
-      name = _parent_name(to_key(key))
+      name = parent_name(to_key(key))
       return if name.nil?
       @h[name]
     end
@@ -126,7 +127,7 @@ module Logging
 
       @h.each_pair do |child,logger|
         next if :root == child
-        ary << logger if parent == _parent_name(child)
+        ary << logger if parent == parent_name(child)
       end
       return ary.sort
     end
@@ -154,7 +155,7 @@ module Logging
     # Returns the name of the parent for the logger identified by the given
     # _key_. If the _key_ is for the root logger, then +nil+ is returned.
     #
-    def _parent_name( key )
+    def parent_name( key )
       return if :root == key
 
       a = key.split PATH_DELIMITER
@@ -166,6 +167,43 @@ module Logging
       p
     end
 
+    # call-seq:
+    #    add_master( 'First::Name', 'Second::Name', ... )
+    #
+    # Add the given logger names to the list of consolidation masters. All
+    # classes in the given namespace(s) will use these loggers instead of
+    # creating their own individual loggers.
+    #
+    def add_master( *args )
+      args.map do |key|
+        key = to_key(key)
+        @masters << key unless @masters.include? key
+        key
+      end
+    end
+
+    # call-seq:
+    #    master_for( key )
+    #
+    # Retruns the consolidation master name for the given _key_. If there is
+    # no consolidation master, then +nil+ is returned.
+    #
+    def master_for( key )
+      return if @masters.empty?
+      key = to_key(key)
+
+      loop do
+        break key if @masters.include? key
+        break nil if :root == key
+
+        if index = key.rindex(PATH_DELIMITER)
+          key = key.slice(0, index)
+        else
+          key = :root
+        end
+      end
+    end
+
   end  # class Repository
 end  # module Logging
 

data/test/layouts/test_pattern.rb

@@ -170,6 +170,27 @@ module TestLayouts
       assert_equal 'tim    ', @layout.format(event)
     end
 
+    def test_pattern_logger_name_precision
+      event = Logging::LogEvent.new('Foo', @levels['info'], 'message', false)
+
+      @layout.pattern = '%c{2}'
+      assert_equal 'Foo', @layout.format(event)
+
+      event.logger = 'Foo::Bar::Baz::Buz'
+      assert_equal 'Baz::Buz', @layout.format(event)
+
+      assert_raise(ArgumentError) {
+        @layout.pattern = '%c{0}'
+      }
+
+      @layout.pattern = '%c{foo}'
+      event.logger = 'Foo::Bar'
+      assert_equal 'Foo::Bar{foo}', @layout.format(event)
+
+      @layout.pattern = '%m{42}'
+      assert_equal 'message{42}', @layout.format(event)
+    end
+
   end  # class TestBasic
 end  # module TestLayouts
 end  # module TestLogging

data/test/test_consolidate.rb

@@ -0,0 +1,46 @@
+
+require File.join(File.dirname(__FILE__), %w[setup])
+
+module TestLogging
+
+  class TestConsolidate < Test::Unit::TestCase
+    include LoggingTestCase
+
+    def test_root
+      Logging.consolidate :root
+      root = Logging.logger.root
+
+      assert_same root, Logging.logger['Foo']
+      assert_same root, Logging.logger['Foo::Bar']
+      assert_same root, Logging.logger[Array]
+    end
+
+    def test_foo
+      Logging.consolidate 'Foo'
+      logger = Logging.logger['Foo::Bar::Baz']
+
+      assert_same Logging.logger['Foo'], logger
+      assert_not_same Logging.logger.root, logger
+    end
+
+    def test_many
+      Logging.consolidate 'Foo', 'root', 'Foo::Bar::Baz'
+
+      root = Logging.logger.root
+      foo = Logging.logger['Foo']
+      fbb = Logging.logger['Foo::Bar::Baz']
+
+      assert_not_same root, foo
+      assert_not_same root, fbb
+      assert_not_same foo, fbb
+
+      assert_same root, Logging.logger[Hash]
+      assert_same root, Logging.logger['ActiveRecord::Base']
+      assert_same foo, Logging.logger['Foo::Bar']
+      assert_same fbb, Logging.logger['Foo::Bar::Baz::Buz']
+    end
+
+  end  # class TestConsolidate
+end  # module TestLogging
+
+# EOF

data/test/test_logger.rb

@@ -6,10 +6,6 @@ module TestLogging
   class TestLogger < Test::Unit::TestCase
     include LoggingTestCase
 
-    def setup
-      super
-    end
-
     def test_initialize
       assert_nothing_raised {::Logging::Logger[:test]}
       assert_equal ::Logging::Logger[:test], ::Logging::Logger['test']

data/test/test_repository.rb

@@ -120,6 +120,38 @@ module TestLogging
       assert_equal 'blah', @repo.to_key(:blah)
     end
 
+    def test_add_master
+      ary = @repo.instance_variable_get(:@masters)
+      assert true, ary.empty?
+
+      @repo.add_master 'root'
+      assert_equal [:root], ary
+
+      @repo.add_master Object, 'Foo'
+      assert_equal [:root, 'Object', 'Foo'], ary
+    end
+
+    def test_master_for
+      assert_nil @repo.master_for('root')
+      assert_nil @repo.master_for('Foo::Bar::Baz')
+
+      @repo.add_master('Foo')
+      assert_equal 'Foo', @repo.master_for('Foo')
+      assert_equal 'Foo', @repo.master_for('Foo::Bar::Baz')
+
+      @repo.add_master('Foo::Bar::Baz')
+      assert_equal 'Foo', @repo.master_for('Foo')
+      assert_equal 'Foo', @repo.master_for('Foo::Bar')
+      assert_equal 'Foo::Bar::Baz', @repo.master_for('Foo::Bar::Baz')
+      assert_equal 'Foo::Bar::Baz', @repo.master_for('Foo::Bar::Baz::Buz')
+
+      assert_nil @repo.master_for('Bar::Baz::Buz')
+      @repo.add_master 'root'
+      assert_equal :root, @repo.master_for('Bar::Baz::Buz')
+      assert_equal 'Foo', @repo.master_for('Foo::Bar')
+      assert_equal 'Foo::Bar::Baz', @repo.master_for('Foo::Bar::Baz::Buz')
+    end
+
   end  # class TestRepository
 end  # module TestLogging
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: logging
 version: !ruby/object:Gem::Version 
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors: 
 - Tim Pease
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-04-17 00:00:00 -06:00
+date: 2009-04-21 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -62,6 +62,7 @@ files:
 - data/simple_logging.rb
 - examples/appenders.rb
 - examples/classes.rb
+- examples/consolidation.rb
 - examples/formatting.rb
 - examples/hierarchies.rb
 - examples/layouts.rb
@@ -124,6 +125,7 @@ files:
 - test/layouts/test_yaml.rb
 - test/setup.rb
 - test/test_appender.rb
+- test/test_consolidate.rb
 - test/test_layout.rb
 - test/test_log_event.rb
 - test/test_logger.rb
@@ -175,6 +177,7 @@ test_files:
 - test/layouts/test_pattern.rb
 - test/layouts/test_yaml.rb
 - test/test_appender.rb
+- test/test_consolidate.rb
 - test/test_layout.rb
 - test/test_log_event.rb
 - test/test_logger.rb