man Log::Agent () - logging agent


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 =>
         -prefix      => $0,
         -showpid     => 1,
         -channels    => {
             'error'  => "$0.err",
             'output' => "$0.out",
             'debug'  => "$0.dbg",


The CWLog::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 CWLog::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.



The CWLog::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 CWLog::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 CWLog::Agent class defines three logging channels, which are CWerror, CWoutput and CWdebug. 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 CWLog::Agent::Driver::Default driver, remaps CWerror and CWdebug to stderr, CWoutput 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 CW%m is handled directly by CWLog::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 CWLog::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:

logdbg priority, message
Debug logging of message to the CWdebug channel. You may specify any priority you want, i.e. a CWdebug priority is not enforced here. You may even specify CW"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 CWnotice priority.
logtrc priority, message
Trace logging of message to the CWoutput channel. Like logdbg() above, you are not restricted to the CWinfo priority. This routine checks the logging level (either explicit as in CW"info:14" or implicit as in CW"notice") against the trace level.
logsay message
Log the message at the CWnotice priority to the CWoutput channel. The logging always takes place under the default CW-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 CWwarning priority to the CWerror 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 CWerror priority to the CWerror channel.
logdie message
Log a fatal message at the CWcritical priority to the CWerror channel, and then dies.
logconfess message
Same as logdie(), but issues a Carp::confess(3) call instead. It is possible to configure the CWLog::Agent module via the CW-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 CWLog::Agent module via the CW-confess switch to automatically redirect a logcroak() to logconfess(), which is invaluable during unit testing.
Returns true when CWLog::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:

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 CWLog::Agent, the following routine is provided. Note that it is not imported by default, i.e. it needs to be explicitely mentionned at CWuse 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 CWdebug, CWerror or CWoutput.

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: 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 CWLog::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. When true, all logdie() calls will be automatically masqueraded as logconfess(). 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. This switch defines the driver object to be used, which must be an heir of the CWLog::Agent::Driver class. See Log::Agent::Driver(3) for a list of the available drivers. Specifies both CW-debug and CW-trace levels at the same time, to a common value. Defines the application name which will be pre-pended to all messages, followed by CW": " (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 CW-prefix switch is kept at the CWLog::Agent level only and is not passed to the driver: it is up to the driver's creation routine to request the CW-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. Request that message priority information be part of the log message. The given parameters are handed off to the creation routine of CWLog::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 CW-priority does not prevent the CW-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. Specifies user-defined tags to be added to each message. The objects given here must inherit from CWLog::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 CWlogtags() 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. Same a CW-debug but applies to logsay(), logwarn(), logerr() and logtrc(). When unspecified, CWLog::Agent runs at the notice level.

Additional routines, not exported by default, are:

Returns a CWLog::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 CW-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. :-)

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 prefixing done when duperr is set in Log::Agent::Driver::File, or the fact that the CWdebug and CWstderr 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?


Raphael Manfredi <>