|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.
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:
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 routines 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 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 implicitely via any logxxx() call.|
|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.|
|logwrite channel, priority, message||Unconditionally write the message at the given priority on channel. The channel can be one of debug, error or output.|
|-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:
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 logging level as described above in
<B>PRIORITIES AND LEVELB>) 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
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 drivers 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:
<B>NOTEB>: 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.
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. :-)
o 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. o Some drivers lack customization and hardwire a few things that come from my personal taste, like the prefixing 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. o 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?
Log::Agent was originally authored by Raphael Manfredi <Raphael_Manfredi@pobox.com> and is currently maintained by Mark Rogaski <firstname.lastname@example.org>.
Copyright (c) 1999-2000 Raphael Manfredi.
Copyright (c) 2002-2003, 2005, 2013 Mark Rogaski; all rights reserved.
This module is free software. You can redistribute it and/or modify it under the terms of the Artistic License 2.0.
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.
|perl v5.20.3||AGENT (3)||2015-11-30|