Title: #{version} Log4r Manual Template: main.html Id: $Id$ #{version} Log4r Manual  

Table of Contents

Scope of this Manual

Most of the API documentation resides in the Log4r RDoc API, so this manual will be brief and targeted to people starting to learn about Log4r or who want to see what Log4r has to offer.

Besides the general overview, a section called The Art of Logging provides tricks and tips in using Log4r efficiently.

Click on the section title to go back to the Table of Contents at any time.

What Log4r Is

Log4r is a comprehensive and flexible logging library written in Ruby for use in Ruby programs. It features a hierarchical logging system of any number of levels, custom level names, logger inheritance, multiple output destinations, execution tracing, custom formatting, thread safteyness, XML and YAML configuration, and more.

Log4r is an adherent to the philosophy of logging using simple print statements. What Log4r adds to this philosophy is a flexible way of controling the information being logged. Log information can be sent to any kind of destination and with varying degrees of importance. Log4r is designed so that logging statements can remain in production code with almost no extra computational cost.

Log4r intends to be easy to use and configure, no matter the complexity. Casual scripts can use Log4r right away with minimal configuration, while more sophisticated applications can set up a structured configuration file in XML or YAML. Comprehensive documentation is provided, with a user's manual, a reference API, and over a dozen examples. Log4r attempts to abide by the Principle of Least Surprise, which means that it works as intended at all points.

Log4r was inspired by and provides much of the features of the Apache Log4j project, but is not a direct implementation or clone. Aside from superficial similarities, the projects are not related in any way and the code base is completely distinct. Log4r was developed without even looking at the Apache Log4j code.

Log4r is an Open Source project and intends to remain that way. The Log4r license is similar to the Ruby Language license. It resides on

While Log4r is interpreted, it attempts to achieve optimal performance and scale well. Already, plans are being made to write the performance-critical components as a C extension to Ruby.

Log4r was inspired by and provides much of the features of the Apache Log4j project, but is not a direct implementation or clone. Aside from superficial similarities, the projects are not related in any way and the code base is completely distinct. Log4r was developed without even looking at the Apache Log4j code.

Log4r is an Open Source project and intends to remain that way. The Log4r license is similar to the Ruby Language license. It resides on this page and in the distribution in a file

Out of the Box

Here's an example of how to use Log4r right away. 
require 'log4r'
include Log4r

# create a logger named 'mylog' that logs to stdout
mylog = Logger.new 'mylog'
mylog.outputters = Outputter.stdout

# Now we can log.
def do_log(log)
  log.debug "This is a message with level DEBUG"
  log.info "This is a message with level INFO"
  log.warn "This is a message with level WARN"
  log.error "This is a message with level ERROR"
  log.fatal "This is a message with level FATAL"
end
do_log(mylog)
The output will look something like this: 
DEBUG mylog: This is a message with level DEBUG
 INFO mylog: This is a message with level INFO
 WARN mylog: This is a message with level WARN
ERROR mylog: This is a message with level ERROR
FATAL mylog: This is a message with level FATAL
For ease of access, the logger is stored in a hashtable keyed to its name: 
mylog = Logger['mylog']        # Get our logger back
Suppose we want to turn off DEBUG, INFO and WARN messages and see only ERROR and FATAL. To do this, we set the level threshold for mylog to ERROR: 
mylog.level = ERROR
Running do_log(mylog) yields: 
ERROR mylog: This is a message with level ERROR
FATAL mylog: This is a message with level FATAL

Overview

We will now go over the components of Log4r. A summary of each is provided, and links to the Log4r RDoc API are provided for further perusal.

Levels

Log4r uses a hierarchical system of logging. That is, certain log events can have a higher priority than other log events. Hence, one can control how much information one wants to log by adjusting the level threshold of logging. By default, the logging levels and priorities are: 
DEBUG < INFO < WARN < ERROR < FATAL
In the previous section, we saw how setting the level to ERROR prevented messages with levels DEBUG, INFO and WARN from showing up. The names and numbers of these levels are configurable. You can have any number of levels and name them whatever you wish. The logging methods we saw in the last section will be named after the custom levels. Log4r adjusts itself to suit your needs.

To find out more about levels, please see rdoc/files/log4r_rb.html.

Loggers

The principle interface in Log4r is a Logger. Loggers have one logging method for each level and any number of output destinations. A logger's level threshold and output destinations may be changed dynamically. Loggers are stored within a Repository for retrieval at any time. Loggers provide all kinds of data for logging: the log message itself, the line number and file it was called in, a timestamp, the log priority, and so on.

Loggers can inherit other Loggers. Inheritance means that a Logger initially adopts the characteristics of its parent if none are specified. A Logger's level is inherited once, and a Logger will write to its parents output destinations as well as its own. This behavior is optional, but allows one to structure a powerful, and easily configurable logging system.

To find out more about loggers, please see rdoc/files/log4r/logger_rb.html.

Outputters

An output destination (file, raw IO, stdout, etc.) is represented by an Outputter object. An Outputter has a particular means of formatting data (Formatter) and has a level threshold of its own. Outputters, like Loggers, are stored in a repository and can be retrieved and manipulated at any time. Every outputter is thread-safe, meaning that multiple threads can log to the same Outputter without worrying about race conditions.

There is a growing collection of outputters provided: raw IO, to stdout, to stderr, to files (including one that splits and zips up logs periodically), to syslog and to an email address. If a specialized Outputter is needed, one can be created from scratch in almost no time, thanks to the ease of extending log4r outputters, the well documented code and the open source license.

To find out more about outputters, please see rdoc/files/log4r/outputter/outputter_rb.html.

Formatters

A Formatter is responsible for rendering a log message into an output format. Several Formatters are provided, including the powerful PatternFormatter. PatternFormatter uses sprintf-like directives to format log messages and eliminates the need for custom Formatters.

To find out more about formatters, please see rdoc/files/log4r/formatter/formatter_rb.html.
To find out more about PatternFormatter, please see rdoc/files/log4r/formatter/patternformatter_rb.html.

Configuration

Configuring Log4r is accomplished via the Configurator and YamlConfigurator classes. They allow one to set custom levels and load up XML or YAML configurations. The XML and YAML grammar used by Log4r is extremely flexible and can accomodate the configuration of custom Outputters and Formatters with no extra work. That is, if a custom Outputter is created, it can immedieately be configured without needing to write extra code. This is acomplished by taking advantage of Ruby's powerful reflection capabilities.

To find out more about configuration, please see rdoc/files/log4r/configurator_rb.html.
For YAML configuration, also see rdoc/files/log4r/yamlconfigurator.html

Remote Logging

It is possible to send log events from an Outputter to a Logger over a network. This is accomplished using the distributed Ruby library ROMP, a subclass of Logger called LogServer, and a RemoteOutputter.

To find out more about remote logging, please see rdoc/files/log4r/logserver_rb.html

Alternatively, one can just send log reports via email using EmailOutputter.

To find out more about EmailOutputter, please see rdoc/classes/Log4r/EmailOutputter.html

The Art of Logging

Log4r in itself does not automatically enable people to understand logging, however it does provide tools to assist in The Art of Logging. We will now cover some of the techniques in this art and how to use Log4r to accomplish them.

Avoiding Parameter Evaluation

Suppose we have a complex structure and don't have the time to make a special to_s method. When we want to log the contents of the object, we end up doing something like this: 
log.debug( myobj.collect{|e| e.collect{|p| p.to_s}} )
It is expensive to do this because every time the debug method is called, the parameters passed to it will be evaluated. Because this is a feature of Ruby, setting the logger to OFF will not prevent the evaluation. There are two ways to get around parameter evaluation. The first is to perform a simple if condition: 
if log.debug?
  log.debug( myobj.collect{|e| e.collect{|p| p.to_s}} )
end
Here we are introduced to log.debug?, which is called a query method. It returns true if DEBUG messages are being logged, otherwise it returns false. Query methods are very cheap to invoke and are a great way to encapsulate complext logging statements. The query methods, like the logging ones, are named after the levels, but with a question mark at the end. As another example, log.info? will find out if INFO is being logged and so on.

The second way around parameter evaluation is to pass a block to the logging method: 

log.debug { myobj.collect{|e| e.collect{|p| p.to_s} }
The block will be evaluated if and only if the logger is capable of handling DEBUG log events.

How Many?

How many loggers should one have? Only experience can tell, but a general rule of thumb is to create one static logger per class and one per service or state.

When dealing with a large number of loggers, logger inheritance and additivity can help organize what gets logged and to where.

The configuration possibilities in Log4r are uncountable and can sometimes be daunting. It's best to start with something simple and evolve it over time. To assist in this task, Log4r can be set up using XML or YAML configuration files.

Where To?

Log4r lets one associate any number of Outputters to a Logger. Logger additivity enables propagation of a log event upwards in the logger hierarchy. The outputters themselves can have their own level thresholds. Unlike normal loggers, Outputters can log at certain specific log levels. this allows one to channel particular data to a particular output. All things considered, log4r offers tremendous flexibility in deciding what gets logged where.

Where From?

Want to find out where a particular log statement came from? Loggers have tracers which record the call stack when turned on: 
Logger['mylog'].trace = true
The trace is then accesible by a Formatter.

Who's Talking?

If there are many loggers that use logger inheritance, it's occasionally a good idea to show the full ancestry of a logger in the log statement. Here's how to set up PatternFormatter to show the full ancestry of a logger in a logging statement (in XML): 
<formatter type="PatternFormatter">
  <!-- %C shows full ancestry -->
  <pattern>[%l %C] %m</pattern>
</formatter>
For a logger named 'me' with ancestors 'cain::grandpa::pa', it will produce: 
[DEBUG cain::grandpa::pa::me] Log message

The Null Logger

In addition to being the parent of all loggers, Logger.root is a null object. That means that it does absolutely nothing when its log methods are invoked. Its query methods always return false and it has no outputters. It is useful to turn loggers off from within code: 
noisylog = Logger.root
noisy.debug "This won't do anything"

Gotchas

If you are using Log4r, there are a few gotchas that you should be aware of:

Performance

Profiling has revealed that log4r is typically an order of magnitude or two slower than log4j. However, this is still damn fast! In particular, if a logger is set to OFF, the overhead of checking to see if a log event should be logged nearly vanishes. This was accomplished by dynamically redefining the unloggable logging methods to do nothing.

In the future, Log4r's performance critical features will be written as a C extension to Ruby. It will still be optional, but it will be available for those who absolutely need to squeeze every last ounce of performance out of Log4r. (No longer in the works, unfortunately.)

The Project Itself

Log4r was initially developed by one person and is slowly but surely gaining popularity and new developers. Please refer to the contact page for more information on the developers.