File: log4r.rb

log4r.rb |
Path: | /home/cepheus/projects/prep/log4r-1.0.1/src/log4r.rb
Created: | Mon Jan 28 21:59:41 PST 2002
Modified: | Mon Jan 28 08:05:47 PST 2002

# Log4r API

## First things first

The code examples in this API assume:

      include Log4r

This API is tailored for reference. As usual, more information and documentation can be found in the actual sourcecode.

## Log Levels

Log4r provides as many levels of logging as desired. Logging levels are an ordered set of names ranked by priority. The more important a level is, the higher its priority and the more likely we want to see any data associated with it. This scheme allows one to fine tune the amount and class of log data that one sees in a particular set of views.

There are two classes with adjustable level tuning: Loggers and Outputters. They each have a level threshold, which is a mask on unwanted data below a certain priority. Additionally, Outputters can be set to mask out any set of levels.

By combining level tuning with other Log4r features, one can direct any set of data to any destination desired in a way that is easy to visualize and configure.

### Default Levels

The default log levels and their priority rankings are:

      DEBUG < INFO < WARN < ERROR < FATAL

### Custom Levels

You can have as many levels as you desire, with any naming scheme. Log4r will automatically define level constants and log method names after your custom specification.

Please see log4r/configurator.rb for details.

### Boundary Levels

There are two special levels, `ALL` and `OFF` which denote whether we are logging at all levels or at none. The priority ranks with respect to the logging levels are as follows:

      ALL < logging levels < OFF

Thus, setting the level to `ALL` will enable logging at all levels whereas `OFF` will turn off logging completely.

## Usage Guidelines

For Loggers: | log4r/logger.rb
For Outputters: | log4r/outputter/outputter.rb
For Formatters: | log4r/formatter/formatter.rb
For configuration: | log4r/configurator.rb

## Principal Classes of Log4r

- Log4r::Logger - Interface to logging
- Log4r::Outputter - An output destination for a logger.
- Log4r::Formatter - A means of formatting log data.
- Log4r::Configurator - A means of configuring Log4r

## Convenience Classes

Log4r provides several convenience Outputters and Formatters. Please look at the useage guidelines for the respective classes for a list.

## Remote Logging

Log4r provides a way to send log events over a network. See log4r/logserver.rb for details.

## What's Going on Inside?

Log4r has an internal logger which records much of what goes on inside. To see the output, define a Logger named 'log4r' and give it an Outputter of some sort. It logs only at the lowest and highest priorities. That would be DEBUG and FATAL for the standard setup.

It is essential to view this data when using certain classes, like Log4r::LogServer and Log4r::EmailOutputter.

## Other Info

Author: | Leon Torres
Version: | $Id: log4r.rb,v 1.9 2002/01/28 16:05:47 cepheus Exp $

Required files

"log4r/outputter/fileoutputter" "log4r/outputter/consoleoutputters" "log4r/outputter/staticoutputter" "log4r/formatter/patternformatter" "log4r/loggerfactory"

Classes and Modules

Module Log4r
::Class Log4r::LogEvent
::Class Log4r::Outputter
::Class Log4r::DefaultFormatter
::Class Log4r::RemoteOutputter
::Class Log4r::Logger
::Class Log4r::Configurator
::Class Log4r::RootLogger
::Class Log4r::ObjectFormatter
::Class Log4r::StderrOutputter
::Class Log4r::EmailOutputter
::Class Log4r::Formatter
::Class Log4r::StdoutOutputter
::Class Log4r::ConfigError
::Class Log4r::BasicFormatter
::Class Log4r::SimpleFormatter
::Class Log4r::PatternFormatter
::Class Log4r::LogServer
::Class Log4r::FileOutputter
::Class Log4r::IOOutputter
::Class Log4r::Log4rTools