1.0.5 Log4r API Reference

Welcome to the Log4r API reference. There are two classes of reference, the file overview and the class API. They are listed under Files and Classes respectively. File overviews cover the use of the Log4r API and some implementation details, whereas class APIs detail the methods available to the various objects.

The code examples in this API assume:

  include Log4r

This file overview covers some of the major concepts in Log4r.

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. Log4r provides many ways to filter information by level.

Loggers and Outputters have a level parameter which serves as a level threshold. Any data below this threshold will be ignored by the Logger or Outputter. Additionally, Outputters can be set to mask out any particular level or collection of levels.

By combining level thresholds 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 as defined by user < OFF

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

File Overviews

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 file overviews of those classes for more details.

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