agent(3)
NAME
Log::Agent - logging agent
SYNOPSIS
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",
},
)
);
DESCRIPTION
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 log
ging 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 log
files, 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.
PRIORITIES AND LEVEL
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::Pri
orities 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 under
lying driver for logging. They are used by the logtrc()
and logdbg() routines, respectively.
CHANNELS
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 (typi
cally 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).
INTERFACE
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 fail
ing system call.
NOTE: There should not be any trailing "0 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! There
fore, 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 mod
ules: - logdbg priority, message
- 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. - logtrc priority, message
- 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. - logsay message
- Log the message at the "notice" priority to the "out
put" 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). - logwarn message
- Log a warning message at the "warning" priority to the
"error" channel. - logcarp message
- Same as logwarn(), but issues a Carp::carp(3) call
instead, which will warn from the perspective of the
routine's caller. - logerr message
- Log an error message at the "error" priority to the
"error" channel. - logdie message
- Log a fatal message at the "critical" priority to the
"error" channel, and then dies. - logconfess message
- Same as logdie(), but issues a Carp::confess(3) call
instead. It is possible to configure the "Log::Agent"
module via the "-confess" switch to automatically
redirect a logdie() to logconfess(), which is invalu able during unit testing. - logcroak message
- Same as logdie(), but issues a Carp::croak(3) call
instead. It is possible to configure the "Log::Agent"
module via the "-confess" switch to automatically
redirect a logcroak() to logconfess(), which is invaluable during unit testing. - Log::Agent::inited
- Returns true when "Log::Agent" was initialized, either
explicitely via a logconfig() or implicitely via any logxxx() call. - Modules sometimes wish to report errors from the perspec
tive of their caller's caller, not really their caller.
The following interface is therefore provided: - logxcarp offset, message
- Same a logcarp(), but with an additional offset to be
applied on the stack. To warn one level above your
caller, set it to 1. - logxcroak offset, message
- Same a logcroak(), but with an additional offset to be
applied on the stack. To report an error one level
above your caller, set it to 1. - 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. - logwrite channel, priority, message
- Unconditionally write the message at the given prior_ ity on channel. The channel can be one of "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 follow ing 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
- When true, all logdie() calls will be automatically masqueraded as logconfess().
- "-debug" => priority or level
- Sets the priority threshold (can be expressed as a
string or a number, the string being mapped to a log
ging 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
- This switch defines the driver object to be used,
which must be an heir of the "Log::Agent::Driver"
class. See Log::Agent::Driver(3) for a list of the available drivers. - "-level" => priority or level
- Specifies both "-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 rou
tine 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 log_
warn() 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 mes
sage. 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:
- logtags
- 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" argu ment. 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 opera
tions that can be performed.
KNOWN LIMITATIONS
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. :-)
- · A module which calls logdie() may have its die trapped
- if called from within an eval(), but unfortunately,
the value of $@ is unpredictable: it may be prefixed
or not depending on the driver used. This is harder to
fix as one might think of at first glance. - · Some drivers lack customization and hardwire a few
- things that come from my personal taste, like the pre
fixing done when duperr is set in
Log::Agent::Driver::File, or the fact that the "debug"
and "stderr" channels are merged as one in the
Log::Agent::Driver::Default driver. - · When using logcroak() or logconfess(), the place where
- the call was made can still be visible when -caller is
used, since the addition of the caller information to
the message is done before calling the logging driver.
Is this a problem?
AUTHOR
Raphael Manfredi <Raphael_Manfredi@pobox.com>