logger.rb
Path: /home/cepheus/projects/prep/log4r-1.0.0/src/log4r/logger.rb
Created: Wed Jan 16 05:21:51 PST 2002
Modified: Tue Jan 15 22:28:07 PST 2002

Loggers

Loggers provide the interface for logging in Log4r. To create a logger, first come up with a good name for it. Good choices include the name of the class using it, a service name, or the name of the file. Let's create a logger named 'mylog':

  Logger.new('mylog')

After creating a logger, it is stashed in Log4r::Repository. You may retrieve the logger transparently at any time by using a hash method call:

  Logger['mylog']        # get mylog back

Manipulating Outputters

Loggers start out with no Outputters. You can set and manipulate Outputters like so:

  foo = Logger.new('foo')
  foo.outputters = out1, out2, out3    # out# are outputter names or references
  foo.add(out4, out5)
  foo.outputters.each{|o| o.close}     # closses all 5 outs

Please see log4r/outputter.rb and Log4r::Outputter for more about Outputters.

Custom Levels

Suppose you want the following levels and ranks:

  Foo < Bar < Baz

This is easily accomplished:

  Logger.custom_levels('Foo', 'Bar', :Baz)

Custom levels must have names that are valid for Ruby constants. Also, custom levels should be set before anything else is done with Log4r. Otherwise, the default levels will be loaded.

Logging Methods

The logging methods are named after the lowercased level names:

  log.bar "something"        # log at custom level Bar
  log.bar?                   # are we logging at level Bar?

ALL and OFF can be querried, but not logged:

  log.off?                    # true iff level is OFF
  log.all?                    # true iff level is ALL
  log.all "Try to log"        => Method not defined. (NameError)

Inheritance

Normally, when a logger is created, its parent is set to RootLogger. If a Logger's level isn't specified at creation, it will inherit the level of its parent.

To specify an ancestors of a logger besides RootLogger, include the names of the ancestors in order of ancestry and delimited by Log4r::Log4rConfig::LoggerPathDelimiter. For example, if the delimiter is the default ::, our logger is 'me' and its ancestors are 'cain', 'grandpa', and 'pa', we create the logger like so:

  Logger.new('cain::grandpa::pa::me')

This string is split into three compontents which can be used by a Formatter to avoid parsing the name:

Logger#fullname
The whole enchilada.
Logger#name
Just 'me'
Logger#path
'cain::grandpa::pa'

To get this logger back from the repository,

  Logger['cain::grandpa::pa::me']

Outputter Inheritance

By default, Logger Outputters are additive. This means that a log event will also be sent to all of a logger's ancestors. To stop this behavior, set a logger's additive to false.

  Logger['foo'].additive = false

A Logger's level, additivity and trace can be changed dynamically, but this is an expensive operation as the logging methods have to be redefined.

Implementation details are covered in loggerfactory.rb. End users need not worry about them.

RootLogger

Log4r::RootLogger is the ancestor of all loggers. Its level defines the global logging threshold. Any loggers created after RootLogger's level is set will not log below that level. By default, RootLogger's level is set to ALL

RootLogger is a singleton which gets created automatically. You can retrieve it transparently with Logger.root, Logger.global, Logger['root'] or Logger['global']. We want everything to ignore events less than FATAL

  Logger.global.level = FATAL

RootLogger Does Nothing

RootLogger itself behaves as if its level were permanently set to OFF, thus making it a sort of null object. If you are feeling silly, you can replace a logger with RootLogger instead of setting that logger to OFF.

Other Info

Version:$Id: logger.rb,v 1.18 2002/01/16 06:28:07 cepheus Exp $
Author:Leon Torres <leon@ugcs.caltech.edu>

Required files
"thread"    "log4r/outputter"    "log4r/repository"    "log4r/loggerfactory"   
Classes and Modules
Module Log4r
  ::Class Log4r::Outputter
  ::Class Log4r::DefaultFormatter
  ::Class Log4r::NullFormatter
  ::Class Log4r::Logger
  ::Class Log4r::Configurator
  ::Class Log4r::ObjectFormatter
  ::Class Log4r::RootLogger
  ::Class Log4r::StderrOutputter
  ::Class Log4r::Formatter
  ::Class Log4r::StdoutOutputter
  ::Class Log4r::ConfigError
  ::Class Log4r::BasicFormatter
  ::Class Log4r::SimpleFormatter
  ::Class Log4r::PatternFormatter
  ::Class Log4r::FileOutputter
  ::  ::Class Log4r::FileOutputter::RingBuffOutputter