File: configurator.rb

configurator.rb |
Path: | /home/cepheus/projects/prep/log4r-1.0.1/src/log4r/configurator.rb
Created: | Mon Jan 28 21:59:41 PST 2002
Modified: | Mon Jan 28 19:39:23 PST 2002

# Configuring Log4r

## Requirements

To use this class,

      require 'log4r/configurator'

REXML is required for XML configuration. Get REXML at http://www.ruby-lang.org/en/raa-list.rhtml?name=REXML

## Custom Levels

Suppose you want the following levels and ranks:

      Foo < Bar < Baz

This is easily accomplished:

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

The method accepts strings or symbols. However, 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.

You can set custom levels in XML. That's covered in the following section.

## XML Configuration

If you have REXML (and soon, NQXML), you can configure Log4r with XML. To do this, first write an XML configuration (which you can learn by studying this document and the examples provided in the distribution) and then load up the XML from within your program as follows:

      Configurator.load_xml_file('/path/to/file.xml')

Hopefully the error messages are succint enough to make XML configuration painless.

The Log4r XML configuration system is very flexible and powerful. In fact, it is somewhat preferable to configuring Log4r in Ruby. To begin understanding the system, we must first grok the things you can do. Coincidentially, these things have names associated with them. The following three sections cover what one must grok.

### Grok this: XML Directives

The expressive power of Ruby has enabled a feature I call XML directives. An XML directive is a name-value pair belonging to some element. It may be represented as an attribute (name="value") of the element, or as a child (<name>value</name>) of the element. Therefore, you are free to specify information about an object as either an attribute or an element. An example should clarify:

      <object data="value"/>

Is equivalent to:

      <object>
        <data>value</data>
      </object>

You can assume this behavior except where noted elsewhere in the API.

### Grok this: XML Parameters

A scheme which I call XML parameters enables one to utilize the XML configuratin system for custom Outputters and Formatters. This requires no extra work on your part, so long as your objects are set up using hash arguments and can decode string values.

An XML parameter is analogous to a hash argument to some object's `new` method. Consider these hash arguments to FileOutputter:

      :filename => '/path/to/logs/my.log'
      :trunc => 'true'

We can specify them in XML like this:

      <outputter type="FileOutputter" trunc="true">
        <filename>/path/to/logs/my.log</filename>
        ...

The name of the element/attribute is just the name of the parameter. Note that the input will be a string. Now let's suppose you have defined a custom Outputter named MyOutputter with the following additional hash args:

      :myarg1 => 'foo'
      :myarg2 => '123'

Automagically, you can configure your Outputter like so:

      <outputter type="MyOutputter" myarg2="123">
        <myarg1>foo</myarg1>
        ...

Isn't that nice? `:-)`

### Grok this: Variable Substitution

To kill the need for preprocessors, Configurator provides a means of variable substitution for XML parameters at runtime. If you specify `#{foo}` in an XML parameter value, Configurator will replace it with the value of 'foo' in its parameter hashtable. The primary idea is that you can figure stuff out in your program, say the log path, and relay that information to the XML while it's being loaded. Secondarily, it is a way to have aliases within an XML document.

There are two ways to tell Configurator about these variables. The first method we'll cover is done within a Ruby program with Configurator[].

      Configurator['logpath'] = '/path/to/logs'

Thereafter, any occurence of #{logpath} in each and every XML parameter will be substituted with '/path/to/logs'.

      <filename>#{logpath}/mylog.log</filename> => '/path/to/logs/mylog.log'

The second way is to define `parameters` in the XML:

      <pre_config>
        <parameter name="logpath" value="/path/to/logs'/>
        <parameter name="other" value="somethingelse'/>
        ...
      </pre_config>

Alternatively,

      <pre_config>
        <parameters>
          <logpath>/path/to/logs</logpath>
          <other>somethingelse</other>
          ...
        </parameters>
        ...

The end result is the same, but isn't as flexible as the first, which is done at runtime.

# XML Grammar

And now, here's the XML grammar we use to configure Log4r.

## Root Element

The root element is `<log4r_config>`. It can be embedded as a node of any other element in an XML file.

## Pre-config element

The pre_config element is a child of log4r_config and contains:

- 'custom_levels' element
- 'global' element
- 'parameters' element
- any number of 'parameter' elements

### Custom Levels

The custom_levels element is not an XML directive of pre_config. It must be specified like so:

      <custom_levels>Foo, Bar, Baz</custom_levels>

### Global Level

       <global level="DEBUG"/>

or

       <global><level>DEBUG</level></global>

Here, level is an XML directive of global.

### Parameters

We covered this already.

      <parameter name="param name 1" value="param value 1">
      <parameter name="param name 2" value="param value 2">
      ...
      <parameters>
        <param3>value3</param3>
        <param4>value3</param4>
        ...

### Example

       <log4r_config>
         <pre_config>
           <custom_levels>Foo,Bar, Baz</custom_levels>
           <global level="Bar"/>
           <parameters>
             <logpath>/var/log/foo</logpath>
             <mypattern>%l [%d] %m</mypattern>
           </parameters>
         </pre_config>
         ...
         <!-- define some outputters and loggers -->
         ...
       </log4r_config>

## Configuring Other Objects

The XML configuration grammar for Loggers, Outputters and the like are covered in the usage guidelines for those classes.

## Order Doesn't Matter

You can (it is hoped) define any of the XML objects in any order desired.

## Other Info

Version: | $Id: configurator.rb,v 1.10 2002/01/29 03:39:23 cepheus Exp $
Author: | Leon Torres <leon@to.ugcs.caltech.edu>

Required files

"log4r/logger" "log4r/outputter/staticoutputter" "log4r/lib/xmlloader" "log4r/logserver" "log4r/outputter/remoteoutputter"

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