logging 0.9.8 → 1.0.0

data/History.txt

@@ -1,3 +1,16 @@
+== 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
+1 bug fix
+  - Logging initialization happens implicitly when a logger, layout, or
+    appender is created
+
 == 0.9.8 / 2009-04-11
 
 2 minor enhancements

data/README.rdoc

@@ -14,7 +14,7 @@ formatting, and more.
 
 == INSTALL
 
-   sudo gem install logging
+  sudo gem install logging
 
 == EXAMPLE
 
@@ -22,58 +22,70 @@ This example configures a logger to output messages in a format similar to the
 core ruby Logger class. Only log messages that are warnings or higher will be
 logged.
 
-   require 'logging'
+  require 'logging'
 
-   logger = Logging.logger(STDOUT)
-   logger.level = :warn
+  logger = Logging.logger(STDOUT)
+  logger.level = :warn
 
-   logger.debug "this debug message will not be output by the logger"
-   logger.warn "this is your last warning"
+  logger.debug "this debug message will not be output by the logger"
+  logger.warn "this is your last warning"
 
 In this example, a single logger is crated that will append to STDOUT and to a
 file. Only log messages that are informational or higher will be logged.
 
-   require 'logging'
+  require 'logging'
 
-   logger = Logging::Logger['example_logger']
-   logger.add_appenders(
-       Logging::Appender.stdout,
-       Logging::Appenders::File.new('example.log')
-   )
-   logger.level = :info
+  logger = Logging.logger['example_logger']
+  logger.add_appenders(
+      Logging.appenders.stdout,
+      Logging.appenders.file('example.log')
+  )
+  logger.level = :info
 
-   logger.debug "this debug message will not be output by the logger"
-   logger.info "just some friendly advice"
+  logger.debug "this debug message will not be output by the logger"
+  logger.info "just some friendly advice"
 
 The Logging library was created to allow each class in a program to have its
 own configurable logger. The logging level for a particular class can be
 changed independently of all other loggers in the system. This example shows
 the recommended way of accomplishing this.
 
-   require 'logging'
-
-   Logging::Logger['FirstClass'].level = :warn
-   Logging::Logger['SecondClass'].level = :debug
-
-   class FirstClass
-     def initialize
-       @log = Logging::Logger[self]
-     end
-
-     def some_method
-       @log.debug "some method was called on #{self.inspect}"
-     end
-   end
-
-   class SecondClass
-     def initialize
-       @log = Logging::Logger[self]
-     end
-
-     def another_method
-       @log.debug "another method was called on #{self.inspect}"
-     end
-   end
+  require 'logging'
+
+  Logging.logger['FirstClass'].level = :warn
+  Logging.logger['SecondClass'].level = :debug
+
+  class FirstClass
+    def initialize
+      @log = Logging.logger[self]
+    end
+
+    def some_method
+      @log.debug "some method was called on #{self.inspect}"
+    end
+  end
+
+  class SecondClass
+    def initialize
+      @log = Logging.logger[self]
+    end
+
+    def another_method
+      @log.debug "another method was called on #{self.inspect}"
+    end
+  end
+
+There are many more examples in the "examples" folder of the logging
+package. The recommended reading order is the following:
+
+  simple.rb
+  loggers.rb
+  classes.rb
+  hierarchies.rb
+  names.rb
+  appenders.rb
+  layouts.rb
+  formatting.rb
 
 == NOTES
 

data/Rakefile

@@ -27,6 +27,7 @@ PROJ.ignore_file = '.gitignore'
 
 PROJ.exclude << %w[^tags$ logging.gemspec]
 PROJ.rdoc.exclude << '^data'
+PROJ.rdoc.include << '^examples/.*\.rb'
 #PROJ.rdoc.dir = 'doc/rdoc'
 #PROJ.rdoc.remote_dir = 'rdoc'
 PROJ.rdoc.dir = 'doc'

data/examples/appenders.rb

@@ -0,0 +1,44 @@
+#
+# Appenders are used to output log events to some logging destination. The
+# same log event can be sent to multiple desitnations by associating
+# multiple appenders with the logger.
+#
+# The following is a list of all the available appenders and a brief
+# description of each. Please refer to the documentation for specific
+# configuration options available for each.
+#
+#   Email         generates e-mail messages
+#   File          writes to a regular file
+#   Growl         outputs growl notifications (Mac OS X only)
+#   IO            generic IO appender
+#   RollingFile   writes to a file and rolls based on size or age
+#   Stdout        appends to STDOUT
+#   Stderr        appends to STDERR
+#   StringIo      writes to a StringIO instance (useful for testing)
+#   Syslog        outputs to syslogd (not available on all systems)
+#
+# And you can access these appenders:
+#
+#   Logging.appenders.email
+#   Logging.appenders.file
+#   Logging.appenders.growl
+#   Logging.appenders.io
+#   Logging.appenders.rolling_file
+#   Logging.appenders.stdout
+#   Logging.appenders.stderr
+#   Logging.appenders.string_io
+#   Logging.appenders.syslog
+#
+
+  require 'logging'
+
+  log = Logging.logger['example']
+  log.add_appenders(
+      Logging.appenders.stdout,
+      Logging.appenders.file('development.log')
+  )
+  log.level = :debug
+
+  # These messages will be logged to both the log file and to STDOUT
+  log.debug "a very nice little debug message"
+  log.warn "this is your last warning"

data/examples/classes.rb

@@ -0,0 +1,39 @@
+#
+# The Logging framework is very good about figuring out predictable names
+# for loggers regardless of what object is used to create them. The name is
+# the class name or module name of whatever is passed to the logger bracket
+# method. The following lines all return the exact same logger instance:
+#
+#    ary = Array.new
+#    Logging.logger[ary]
+#    Logging.logger[Array]
+#    Logging.logger['Array']
+#    Logging.logger[:Array]
+#
+# So, if you want each class to have it's own logger this is very easy to
+# do.
+#
+
+  require 'logging'
+
+  Logging.logger.root.appenders = Logging.appenders.stdout
+  Logging.logger.root.level = :info
+
+  class Foo
+    attr_reader :log
+    def initialize() @log = Logging.logger[self]; end
+  end
+
+  class Foo::Bar
+    attr_reader :log
+    def initialize() @log = Logging.logger[self]; end
+  end
+
+  foo = Foo.new.log
+  bar = Foo::Bar.new.log
+
+  # you'll notice in these log messages that the logger names were taken
+  # from the class names of the Foo and Foo::Bar instances
+  foo.info 'this message came from Foo'
+  bar.warn 'this is a warning from Foo::Bar'
+

data/examples/formatting.rb

@@ -0,0 +1,49 @@
+#
+# Any Ruby object can be passed to the log methods of a logger. How these
+# objects are formatted by the Logging framework is controlled by a global
+# "format_as" option and a global "backtrace" option.
+#
+# The format_as option allows objects to be converted to a string using the
+# standard "to_s" method, the "inspect" method, or the "to_yaml" method
+# (this is independent of the YAML layout). The format_as option can be
+# overridden by each layout as desired.
+#
+#   Logging.format_as :string   # or :inspect or :yaml
+#
+# Exceptions are treated differently by the logging framework. The Exception
+# class is printed along with the message. Optionally, exception backtraces
+# can be included in the logging output; this option is enabled by default.
+#
+#   Logging.backtrace false
+#
+# The backtrace can be enabled or disabled for each layout as needed.
+#
+
+  require 'logging'
+
+  Logging.format_as :inspect
+  Logging.backtrace false
+
+  Logging.appenders.stdout(
+    :layout => Logging.layouts.basic(:format_as => :yaml)
+  )
+
+  Logging.appenders.stderr(
+    :layout => Logging.layouts.basic(:backtrace => true)
+  )
+
+  log = Logging.logger['foo']
+  log.appenders = %w[stdout stderr]
+
+  # these log messages will all appear twice because of the two appenders -
+  # STDOUT and STDERR - but the interesting thing is the difference in the
+  # output
+  log.info %w[An Array Of Strings]
+  log.info({"one"=>1, "two"=>2})
+
+  begin
+    1 / 0
+  rescue => err
+    log.error err
+  end
+

data/examples/hierarchies.rb

@@ -0,0 +1,71 @@
+#
+# Loggers exist in a hierarchical relationship defined by their names. Each
+# logger has a parent (except for the root logger). A logger can zero or
+# more children. This parent/child relationship is determined by the Ruby
+# namespace separator '::'.
+#
+#   root
+#   |-- Foo
+#   |   |-- Foo::Bar
+#   |   `-- Foo::Baz
+#   |-- ActiveRecord
+#   |   `-- ActiveRecord::Base
+#   |-- ActiveSupport
+#   |   `-- ActiveSupport::Base
+#   `-- Rails
+#
+# A logger inherits its log level from its parent. This level can be set for
+# each logger in the system. Setting the level on a logger affects all it's
+# children and grandchildren, etc. unless the child has it's own level set.
+#
+# Loggers also have a property called "additivity", and by default it is set
+# to true for all loggers. This property enables a logger to pass log events
+# up to its parent.
+#
+# If a logger does not have an appender and its additivity is true, it will
+# pass all log events up to its parent who will then try to send the log
+# event to its appenders. The parent will do the same thing, passing the log
+# event up the chain till the root logger is reached or some parent logger
+# has its additivity set to false.
+#
+# So, if the root logger is the only one with an appender, all loggers can
+# still output log events to the appender because of additivity. A logger
+# will ALWAYS send log events to its own appenders regardless of its
+# additivity.
+#
+# The show_configuration method can be used to dump the logging hierarchy.
+#
+
+  require 'logging'
+
+  Logging.logger.root.level = :debug
+
+  foo = Logging.logger['Foo']
+  bar = Logging.logger['Foo::Bar']
+  baz = Logging.logger['Foo::Baz']
+
+  # configure the Foo logger
+  foo.level = 'warn'
+  foo.appenders = Logging.appenders.stdout
+
+  # since Foo is the parent of Foo::Bar and Foo::Baz, these loggers all have
+  # their level set to warn
+
+  foo.warn 'this is a warning, not a ticket'
+  bar.info 'this message will not be logged'
+  baz.info 'nor will this message'
+  bar.error 'but this error message will be logged'
+
+  # let's demonstrate additivity of loggers
+
+  Logging.logger.root.appenders = Logging.appenders.stdout
+
+  baz.warn 'this message will be logged twice - once by Foo and once by root'
+
+  foo.additive = false
+  bar.warn "foo is no longer passing log events up to it's parent"
+
+  # let's look at the logger hierarchy
+  puts '='*76
+  Logging.show_configuration
+

data/examples/layouts.rb

@@ -0,0 +1,45 @@
+#
+# The formatting of log messages is controlled by the layout given to the
+# appender. By default all appenders use the Basic layout. It's pretty
+# basic. However, a more sophisticated Pattern layout can be used or one of
+# the Parseable layouts -- JSON or YAML.
+#
+# The available layouts are:
+#
+#   Logging.layouts.basic
+#   Logging.layouts.pattern
+#   Logging.layouts.json
+#   Logging.layouts.yaml
+#
+# In this example we'll demonstrate use of different layouts and setting log
+# levels in the appenders to filter out events.
+#
+
+  require 'logging'
+
+  # only show "info" or higher messages on STDOUT using the Basic layout
+  Logging.appenders.stdout(:level => :info)
+
+  # send all log events to the development log (including debug) as JSON
+  Logging.appenders.rolling_file(
+    'development.log',
+    :age    => 'daily',
+    :layout => Logging.layouts.json
+  )
+
+  # send growl notifications for errors and fatals using a nice pattern
+  Logging.appenders.growl(
+    'growl',
+    :level  => :error,
+    :layout => Logging.layouts.pattern(:pattern => '[%d] %-5l: %m\n')
+  )
+
+  log = Logging.logger['Foo::Bar']
+  log.add_appenders 'stdout', 'development.log', 'growl'
+  log.level = :debug
+
+  log.debug "a very nice little debug message"
+  log.info "things are operating nominally"
+  log.warn "this is your last warning"
+  log.error StandardError.new("something went horribly wrong")
+  log.fatal "I Die!"

data/examples/loggers.rb

@@ -0,0 +1,26 @@
+#
+# Multiple loggers can be created and each can be configured with it's own
+# log level and appenders. So one logger can be configured to output debug
+# messages, and all the others can be left at the info or warn level. This
+# makes it easier to debug specific portions of your code.
+#
+
+  require 'logging'
+
+  # all loggers inherit the log level of the "root" logger
+  # but specific loggers can be given their own level
+  Logging.logger.root.level = :warn
+
+  # similarly, the root appender will be used by all loggers
+  Logging.logger.root.appenders = Logging.appenders.file('output.log')
+
+  log1 = Logging.logger['Log1']
+  log2 = Logging.logger['Log2']
+  log3 = Logging.logger['Log3']
+
+  # you can use strings or symbols to set the log level
+  log3.level = 'debug'
+
+  log1.info "this message will not get logged"
+  log2.info "nor will this message"
+  log3.info "but this message will get logged"

data/examples/names.rb

@@ -0,0 +1,40 @@
+#
+# Loggers and appenders can be looked up by name. The bracket notation is
+# used to find these objects:
+#
+#   Logging.logger['foo']
+#   Logging.appenders['bar']
+#
+# A logger will be created if a new name is used. Appenders are different;
+# nil is returned when an unknown appender name is used. The reason for this
+# is that appenders come in many different flavors (so it is unclear which
+# type should be created), but there is only one type of logger.
+#
+# So it is useful to be able to create an appender and then reference it by
+# name to add it to multiple loggers. When the same name is used, the same
+# object will be returned by the bracket methods.
+#
+# Layouts do not have names. Some are stateful, and none are threadsafe. So
+# each appender is configured with it's own layout.
+#
+
+  require 'logging'
+
+  Logging.appenders.file('Debug File', :filename => 'debug.log')
+  Logging.appenders.growl('Growl Notifier', :level => :error)
+
+  # configure the root logger
+  Logging.logger.root.appenders = 'Debug File'
+  Logging.logger.root.level = :debug
+
+  # add the growl notifier to the Critical logger (it will use it's own
+  # appender and the root logger's appender, too)
+  Logging.logger['Critical'].appenders = 'Growl Notifier'
+
+  # if you'll notice above, assigning appenders using just the name is valid
+  # the logger is smart enough to figure out it was given a string and then
+  # go lookup the appender by name
+
+  # and now log some messages
+  Logging.logger['Critical'].info 'just keeping you informed'
+  Logging.logger['Critical'].fatal 'WTF!!'