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 following logging interface is made available to modules:
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.
logdebug message
Log the message at the "debug" priority to the "output" channel.
The difference with logdbg() is twofold: logging is done on the "output" channel, not the "debug"
one, and the priority is implicit.
loginfo message
Log the message at the "info" priority to the "output" channel.
logsay message
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).
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.
logcluck message
Same as logwarn(), but dumps a full stacktrace as well.
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 invaluable 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 explicitly via a logconfig() or implicitly 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:
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 explicitly mentioned 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 priority 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 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
When true, all logdie() calls will be automatically masqueraded as logconfess().
"-debug" => priorityorlevel
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 PRIORITIESANDLEVEL) 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" => priorityorlevel
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 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" => [ listof"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" => priorityorlevel
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"
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.
Install Now
PNG Icons
