Log::Agent - logging agent
use Log::Agent; # in all reusable components logerr "error"; logtrc "notice:12", "notice that" if ...; logdie "log and die";
use Log::Agent; # in application's main logconfig(-prefix => $0); # simplest, uses default driver
use Log::Agent; # another more complex example
require Log::Agent::Driver::File; # logging made to file
logconfig(-driver =>
Log::Agent::Driver::File->make(
-prefix => $0,
-showpid => 1,
-channels => {
'error' => "$0.err",
'output' => "$0.out",
'debug' => "$0.dbg",
},
)
);
The Log::Agent module provides an abstract layer for logging and
tracing, which is independant from the actual method used to physically
perform those activities. It acts as an agent (hence the name) that
collects the requests and delegates processing to a sublayer: the
logging driver.
The Log::Agent module is meant to be used in all reusable components,
since they cannot know in advance how the application which ends up using
them will perform its logging activities: either by emitting messages
on stdout and errors on stderr, or by directing messages to logfiles,
or by using syslog(3).
The logging interface is common for all the logging drivers, and is therefore the result of a compromise between many logging schemes: any information given at this level must be either handled by all drivers, or may be ignored depending on the application's final choice.
WARNING: THIS INTERFACE IS STILL SOMEWHAT ALPHA AND COULD STILL CHANGE DEPENDING ON THE FEEDBACK I SHALL GET FROM USERS AND FROM MY OWN EXPERIENCE USING IT, WITHOUT ANY BACKWARD COMPATIBILITY ASSURANCE.
The Log::Agent module can use both priorities (as defined by
syslog(3)) or logging levels, or either, in which case there is
an implicit computation of the missing item (i.e. the level 4, for
instance, corresponds to the "warning" priority, and vice-versa).
See Log::Agent::Priorities for more details.
A logging level is defined as being a threshold: any level lesser than or equal to that threshold will be logged.
At the Log::Agent level, it is possible to define a trace level and
a debug level. Only the messages below those levels (inclusive) will be
handed out to the underlying driver for logging. They are used by the
logtrc() and logdbg() routines, respectively.
The Log::Agent class defines three logging channels, which are
error, output and debug. Depending on the driver used for
logging, those channels are ignored (typically with syslog()) or may
be implicitely defined (default logging, i.e. the one achieved by the
Log::Agent::Driver::Default driver, remaps error and debug
to stderr, output to stdout).
Anywhere a message is expected, it can be a single string, or a
printf()-like format string followed by the required arguments. The
special macro %m is handled directly by Log::Agent and is replaced
by the string version of $!, which is the last error message returned
by the last failing system call.
NOTE: There should not be any trailing "\n" in the message strings,
nor any embededed one, although this is not enforced. Remember that
the main purpose of Log::Agent is to specify logging messages in a
standard way! Therefore, most of the time, a "should" should be read as
"must" and "should not" as "must not", which is the strongest interdiction
form available in English, as far as I know.
Here are valid message examples:
"started since $time"
"started since %s", $time
"fork: %m"
The follwing logging interface is made available to modules:
Debug logging of message to the debug channel.
You may specify any priority you want, i.e. a debug priority is
not enforced here. You may even specify "notice:4" if you wish,
to have the message logged if the debug level is set to 4 or less.
If handed over to syslog(3), the message will nonetheless be logged at
the notice priority.
Trace logging of message to the output channel.
Like logdbg() above, you are not restricted to the info priority. This
routine checks the logging level (either explicit as in "info:14"
or implicit as in "notice") against the trace level.
Log the message at the notice priority to the output channel.
The logging always takes place under the default -trace settings, but
only if the routine is called, naturally. This means you can still say:
logsay "some trace message" if $verbose;
and control whether the message is emitted by using some external configuration for your module (e.g. by adding a -verbose flag to the creation routine of your class).
warning priority to the error channel.
error priority to the error channel.
critical priority to the error channel,
and then dies.
Log::Agent module via the -confess
switch to automatically redirect a logdie() to logconfess(), which is
invaluable during unit testing.
Log::Agent module via the -confess
switch to automatically redirect a logcroak() to logconfess(), which is
invaluable during unit testing.
Log::Agent was initialized, either explicitely via
a logconfig() or implicitely via any logxxx() call.
Modules sometimes wish to report errors from the perspective of their caller's caller, not really their caller. The following interface is therefore provided:
For applications that wish to implement a debug layer on top of
Log::Agent, the following routine is provided. Note that it is not
imported by default, i.e. it needs to be explicitely mentionned at use
time, since it is not meant to be used directly under regular usage.
debug, error or output.
At the application level, one needs to commit once and for all about the logging scheme to be used. This is done thanks to the logconfig() routine which takes the following switches, in alphabetical order:
-caller => [ parameters ]
Request that caller information (relative to the logxxx() call) be part
of the log message. The given parameters are handed off to the
creation routine of Log::Agent::Tag::Caller and are documented there.
I usually say something like:
-caller => [ -display => '($sub/$line)', -postfix => 1 ]
which I find informative enough. On occasion, I found myself using more complex sequences. See Log::Agent::Tag::Caller.
-confess => flag
-debug => priority or level
Sets the priority threshold (can be expressed as a string or a number, the string being mapped to a logging level as described above in PRIORITIES AND LEVEL) for logdbg() calls.
Calls tagged with a level less than or equal to the given threshold will pass through, others will return prematurely without logging anything.
-driver => driver_object
Log::Agent::Driver class. See Log::Agent::Driver(3) for a list
of the available drivers.
-level => priority or level
-debug and -trace levels at the same time, to a
common value.
-prefix => name
Defines the application name which will be pre-pended to all messages,
followed by ": " (a colon and a space). Using this switch alone will
configure the default driver to use that prefix (stripped down to its
basename component).
When a driver object is used, the -prefix switch is kept at the
Log::Agent level only and is not passed to the driver: it is up to
the driver's creation routine to request the -prefix. Having this
information in Log::Agent enables the module to die on critical errors
with that error prefix, since it cannot rely on the logging driver for
that, obviously.
-priority => [ parameters ]
Request that message priority information be part of the log message.
The given parameters are handed off to the
creation routine of Log::Agent::Tag::Priority and are documented there.
I usually say something like:
-priority => [ -display => '[$priority]' ]
which will display the whole priority name at the beginning of the messages, e.g. "[warning]" for a logwarn() or "[error]" for logerr(). See Log::Agent::Tag::Priority and Log::Agent::Priorities.
NOTE: Using -priority does not prevent the -duperr flag of
the file driver to also add its own hardwired prefixing in front of
duplicated error messages. The two options act at a different level.
-tags => [ list of Log::Agent::Tag objects ]
Specifies user-defined tags to be added to each message. The objects
given here must inherit from Log::Agent::Tag and conform to its
interface. See Log::Agent::Tag for details.
At runtime, well after logconfig() was issued, it may be desirable to
add (or remove) a user tag. Use the logtags() routine for this purpose,
and iteract directly with the tag list object.
For instance, a web module might wish to tag all the messages with a session ID, information that might not have been available by the time logconfig() was issued.
-trace => priority or level
Same a -debug but applies to logsay(), logwarn(), logerr() and logtrc().
When unspecified, Log::Agent runs at the "notice" level.
Additional routines, not exported by default, are:
Returns a Log::Agent::Tag_List object, which holds all user-defined
tags that are to be added to each log message.
The initial list of tags is normally supplied by the application at
logconfig() time, via the -tags argument. To add or remove tags after
configuration time, one needs direct access to the tag list, obtained via
this routine. See Log::Agent::Tag_List for the operations that can be
performed.
The following limitations exist in this early version. They might be addressed in future versions if they are perceived as annoying limitatons instead of being just documented ones. :-)
debug and stderr
channels are merged as one in the Log::Agent::Driver::Default driver.
Raphael Manfredi <Raphael_Manfredi@pobox.com>
Log::Agent::Driver(3), Carp(3).