JezK
Edit File: configurator
= Configuring Log4r with Log4r::Configurator The Configurator class allows one to set up Log4r via XML. Additionally, Configurator contains methods to configure any Log4r defaults. In particular, Configurator provides a method to customize the logging levels. Log4r is also configurable using YAML. For that, there is a class similar to Configurator called Log4r::YamlConfigurator. Please see log4r/yamlconfigurator.rb for details. REXML is required for XML configuration. Get REXML at http://www.ruby-lang.org/en/raa-list.rhtml?name=REXML To use the Configurator class, require 'log4r/configurator' == 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, 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') The Log4r XML configuration system is very flexible and powerful. In fact, it is somewhat preferable to configuring Log4r in Ruby. In order to take full advantage of this feature, there are several concepts one must know. They are covered in the following three sections. === Concept: XML Directives The expressive power of Ruby has enabled a feature I call <i>XML directives</i>. 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. === Concept: XML Parameters A scheme which I call <i>XML parameters</i> enables one to utilize the XML configuratin system for custom Outputters and Formatters. This requires <b>no</b> extra work on your part, so long as your objects are set up using hash arguments and can decode string values. That is, once you've written a custom Outputter, it is automatically configurable in XML without having to write any extra code. An XML parameter is analogous to a hash argument to some object's <tt>new</tt> 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, thus it's wise to convert the data in from strings in any custom classes (to_i for integers, etc). 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? <tt>:-)</tt> === Concept: Variable Substitution To kill the need for preprocessors, Configurator provides a means of variable substitution for XML parameters at runtime. If you specify <tt>#{foo}</tt> 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 <tt>#{logpath}</tt> in each and every XML parameter will be substituted with '/path/to/logs'. For example: <filename>#{logpath}/mylog.log</filename> Becomes, <filename>/path/to/logs/mylog.log</filename> Aside from Configurator[], another way to define XML parameter variables is to define <tt>parameters</tt> under the <tt><pre_config></tt> element of an XML configuration: <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 as using Configurator[]. However, this method is not dynamic. Configurator[] should be used when you want to set variables from within Ruby. = XML Grammar And now, here's the XML grammar we use to configure Log4r. == Root Element The root element is <tt><log4r_config></tt>. It can be embedded as a node of any other element in an XML file. For instance: <my-xml-thing> <customize-libraries> <log4r_config> <!-- log4r configuratin goes here --> </log4r_config> ... == 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 === Pre_config: Custom Levels The custom_levels element is not an <i>XML directive</i> of pre_config. It <b>must</b> be specified like this: <custom_levels>Foo, Bar, Baz</custom_levels> And <b>not</b> like this: <!-- NOT SUPPORTED --> <custom_levels levels="Foo, Bar, Baz"/> === Pre_config: Global Level <global level="DEBUG"/> or <global><level>DEBUG</level></global> Here, level is an XML directive of global. === Pre_config: Parameters Parameters are variables that will be substituted later on. Please see the <b>Concept: Variable Substitution</b> section above. Parameters are <i>XML Directives</i>, which means they can be expressed using elements or attributes. Here is an example: <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> ... === Pre_config: Complete 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 Log4r 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.