PatternFormatter
With PatternFormatter, you get complete control over the appearance of Log4r log events without having to
write custom Formatter classes.
In order to take advantage of PatternFormatter, some familarity with
Kernel#sprintf and Time.strftime is recommended. PatternFormatter accepts
three hash arguments:
pattern: | Log event format string.
| date_pattern: | Date format string.
| date_method: | Date method to call (instead of using date_pattern).
|
The pattern format string is something like "%l [%d]
%80M", which resembles a pattern one would normally pass to
Kernel#sprintf. However, the directives are specific to Log4r. Before we go on, let's cover
some terminology.
Terminology
- %
- The directive identifier. Everything after this up to and including one of
the directive letters defines a directive.
- directive letter
- Letters in the set [cCdtmMl%]. These identify what kind of data
we're interested in. They are detailed below.
- format directive
- The numbers and assorted symbols that appears between % and a
directive letter is a format directive. It is comprised of an
integer specifying the field width followed optionally by a period and an
integer specifying the precision. The field width is the minimum number of
characters to copy from the data string while the precision is the maximum
number to copy. If the field width is preceded by a - sign, the data will
be left-justified. Otherwise, it is right-justified.
- directive
- A statement that says, "I want this data to appear with this
(optional) particular format." A directive starts with a % and
is followed by a format directive and terminates in a directive letter.
What the Directive Letters mean
- c
- Produces a logger's name as in 'me'. Fast.
- C
- Produces a logger's full name as in 'cain::grandpa::pa::me'. Fast.
- d
- Produces the time in a format specified by date_pattern or by
date_method. If neither is specified, the default will be used
(ISO8601). Slow.
- t
- Produces the file and line number of the log event. The appearance varies
by Ruby version, but it is the same output returned by Kernel#caller[0].
Slow.
- m
- The non-inspected log message. That is, to_s called on the object passed
into a log method. Fast.
- M
- The message formatted by the format_object
method in BasicFormatter. It will pretty-print Exceptions, print Strings
and inspect everything else. Slow.
- l
- The name of the level. That's l as in Lambda. Fast.
- %
- %% just prints a %. Any formatting is probably ignored. Fast.
Examples of directives:
- %d
- Prints out the date according to our date_pattern or date_method. By
default, it looks like this: 2001-01-12 13:15:50
- %.120m
- Prints out at most 120 characters of the log message.
- %15t
- Prints the execution trace and pads it on the left with enough whitespace
to make the whole thing 15 chars.
Pattern String
Put a bunch of directives together with some choice formatting characters
and you get a pattern string. For instance:
"[%l] %d :: %.15m" => [DEBUG] 2001-01-12 13:15:50 :: This is a messa
To create a PatternFormatter with this format:
p = PatternFormatter.new :pattern => "[%l] %d :: %.15m"
Formatting time
To format time, you can do one of the following:
- Specify a date_pattern
- Specify what class method of Ruby's Time class to call.
- Use the default format
If neither date_pattern nor date_method is specified, the default date
format will be used. Currently, that would be ISO8601,
The date_pattern is exactly what one would pass to Time.strftime. Please
read up on that for details. To specify a date_pattern, pass
:date_pattern=>"pattern" to PatternFormat.new.
Alternatively, date_method is something like usec or to_s
or any other zero argument Time method that produces a time. More
precisely, the method to call will be invoked on Time.now. To specify a
date_method, pass :date_method=>'methodname' (or a Symbol
equivalent) to PatternFormatter.new.
XML Configuration
As explained in log4r/configurator.rb, the hash
arguments to PatternFormatter are XML parameters. Here's an
example:
<formatter type="PatternFormatter" pattern="[%l] %d :: %.15m">
<date_method>usec</date_method>
</formatter>
Performace considerations
The performance impact of using a particular directive letter is noted in
the What the Directives Letters mean section.
The performance impact of time formatting merits special attention. If you
aren't aware yet, the Time class is kind of a kludge. Time.now.usec happens
to be faster than Time.now. If you're concerned about performance, please
profile the various time methods and patterns.
Other Info
Version: | $Id: patternformatter.rb,v 1.2 2002/01/28 16:05:05 cepheus Exp $
| Author: | Leon Torres <leon@ugcs.caltech.edu>
|
"log4r/formatter/formatter"
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
|