.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Agent 3pm"
.TH Agent 3pm "2016-09-17" "perl v5.22.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Log::Agent \- logging agent
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\& use Log::Agent;            # in all reusable components
\& logerr "error";
\& logtrc "notice:12", "notice that" if ...;
\& logdie "log and die";
\&
\& use Log::Agent;            # in application\*(Aqs 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    => {
\&             \*(Aqerror\*(Aq  => "$0.err",
\&             \*(Aqoutput\*(Aq => "$0.out",
\&             \*(Aqdebug\*(Aq  => "$0.dbg",
\&         },
\&     )
\& );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \f(CW\*(C`Log::Agent\*(C'\fR module provides an abstract layer for logging and
tracing, which is independent 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.
.PP
The \f(CW\*(C`Log::Agent\*(C'\fR 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 \fIsyslog\fR\|(3).
.PP
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.
.SH "PRIORITIES AND LEVEL"
.IX Header "PRIORITIES AND LEVEL"
The \f(CW\*(C`Log::Agent\*(C'\fR module can use both priorities (as defined by
\&\fIsyslog\fR\|(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 \*(L"warning\*(R" priority, and vice-versa).
See Log::Agent::Priorities for more details.
.PP
A logging level is defined as being a threshold: any level lesser than
or equal to that threshold will be logged.
.PP
At the \f(CW\*(C`Log::Agent\*(C'\fR 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
\&\fIlogtrc()\fR and \fIlogdbg()\fR routines, respectively.
.SH "CHANNELS"
.IX Header "CHANNELS"
The \f(CW\*(C`Log::Agent\*(C'\fR class defines three logging channels, which are
\&\f(CW\*(C`error\*(C'\fR, \f(CW\*(C`output\*(C'\fR and \f(CW\*(C`debug\*(C'\fR. Depending on the driver used for
logging, those channels are ignored (typically with \fIsyslog()\fR) or may
be implicitely defined (default logging, i.e. the one achieved by the
\&\f(CW\*(C`Log::Agent::Driver::Default\*(C'\fR driver, remaps \f(CW\*(C`error\*(C'\fR and \f(CW\*(C`debug\*(C'\fR
to stderr, \f(CW\*(C`output\*(C'\fR to stdout).
.SH "INTERFACE"
.IX Header "INTERFACE"
Anywhere a \fImessage\fR is expected, it can be a single string, or a
\&\fIprintf()\fR\-like format string followed by the required arguments. The
special macro \f(CW%m\fR is handled directly by \f(CW\*(C`Log::Agent\*(C'\fR and is replaced
by the string version of $!, which is the last error message returned
by the last failing system call.
.PP
\&\fB\s-1NOTE\s0\fR: There should not be any trailing \*(L"\en\*(R" in the \fImessage\fR strings,
nor any embededed one, although this is not enforced. Remember that
the main purpose of \f(CW\*(C`Log::Agent\*(C'\fR is to specify logging messages in a
standard way!  Therefore, most of the time, a \*(L"should\*(R" should be read as
\&\*(L"must\*(R" and \*(L"should not\*(R" as \*(L"must not\*(R", which is the strongest interdiction
form available in English, as far as I know.
.PP
Here are valid \fImessage\fR examples:
.PP
.Vb 3
\&    "started since $time"
\&    "started since %s", $time
\&    "fork: %m"
.Ve
.PP
The follwing logging interface is made available to modules:
.IP "logdbg \fIpriority\fR, \fImessage\fR" 4
.IX Item "logdbg priority, message"
Debug logging of \fImessage\fR to the \f(CW\*(C`debug\*(C'\fR channel.
.Sp
You may specify any priority you want, i.e.  a \f(CW\*(C`debug\*(C'\fR priority is
not enforced here. You may even specify \f(CW"notice:4"\fR if you wish,
to have the message logged if the debug level is set to 4 or less.
If handed over to \fIsyslog\fR\|(3), the message will nonetheless be logged at
the \f(CW\*(C`notice\*(C'\fR priority.
.IP "logtrc \fIpriority\fR, \fImessage\fR" 4
.IX Item "logtrc priority, message"
Trace logging of \fImessage\fR to the \f(CW\*(C`output\*(C'\fR channel.
.Sp
Like \fIlogdbg()\fR above, you are not restricted to the \f(CW\*(C`info\*(C'\fR priority. This
routine checks the logging level (either explicit as in \f(CW"info:14"\fR
or implicit as in \f(CW"notice"\fR) against the trace level.
.IP "logsay \fImessage\fR" 4
.IX Item "logsay message"
Log the message at the \f(CW\*(C`notice\*(C'\fR priority to the \f(CW\*(C`output\*(C'\fR channel.
The logging always takes place under the default \f(CW\*(C`\-trace\*(C'\fR settings, but
only if the routine is called, naturally.  This means you can still say:
.Sp
.Vb 1
\&    logsay "some trace message" if $verbose;
.Ve
.Sp
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).
.IP "logwarn \fImessage\fR" 4
.IX Item "logwarn message"
Log a warning message at the \f(CW\*(C`warning\*(C'\fR priority to the \f(CW\*(C`error\*(C'\fR channel.
.IP "logcarp \fImessage\fR" 4
.IX Item "logcarp message"
Same as \fIlogwarn()\fR, but issues a \fICarp::carp\fR\|(3) call instead, which will
warn from the perspective of the routine's caller.
.IP "logerr \fImessage\fR" 4
.IX Item "logerr message"
Log an error message at the \f(CW\*(C`error\*(C'\fR priority to the \f(CW\*(C`error\*(C'\fR channel.
.IP "logdie \fImessage\fR" 4
.IX Item "logdie message"
Log a fatal message at the \f(CW\*(C`critical\*(C'\fR priority to the \f(CW\*(C`error\*(C'\fR channel,
and then dies.
.IP "logconfess \fImessage\fR" 4
.IX Item "logconfess message"
Same as \fIlogdie()\fR, but issues a \fICarp::confess\fR\|(3) call instead.  It is
possible to configure the \f(CW\*(C`Log::Agent\*(C'\fR module via the \f(CW\*(C`\-confess\*(C'\fR
switch to automatically redirect a \fIlogdie()\fR to \fIlogconfess()\fR, which is
invaluable during unit testing.
.IP "logcroak \fImessage\fR" 4
.IX Item "logcroak message"
Same as \fIlogdie()\fR, but issues a \fICarp::croak\fR\|(3) call instead.  It is
possible to configure the \f(CW\*(C`Log::Agent\*(C'\fR module via the \f(CW\*(C`\-confess\*(C'\fR
switch to automatically redirect a \fIlogcroak()\fR to \fIlogconfess()\fR, which is
invaluable during unit testing.
.IP "Log::Agent::inited" 4
.IX Item "Log::Agent::inited"
Returns true when \f(CW\*(C`Log::Agent\*(C'\fR was initialized, either explicitly via
a \fIlogconfig()\fR or implicitely via any \fIlogxxx()\fR call.
.PP
Modules sometimes wish to report errors from the perspective of their
caller's caller, not really their caller.  The following interface is
therefore provided:
.IP "logxcarp \fIoffset\fR, \fImessage\fR" 4
.IX Item "logxcarp offset, message"
Same a \fIlogcarp()\fR, but with an additional offset to be applied on the
stack.  To warn one level above your caller, set it to 1.
.IP "logxcroak \fIoffset\fR, \fImessage\fR" 4
.IX Item "logxcroak offset, message"
Same a \fIlogcroak()\fR, but with an additional offset to be applied on the
stack.  To report an error one level above your caller, set it to 1.
.PP
For applications that wish to implement a debug layer on top of
\&\f(CW\*(C`Log::Agent\*(C'\fR, the following routine is provided.  Note that it is not
imported by default, i.e. it needs to be explicitly mentionned at \f(CW\*(C`use\*(C'\fR
time, since it is not meant to be used directly under regular usage.
.IP "logwrite \fIchannel\fR, \fIpriority\fR, \fImessage\fR" 4
.IX Item "logwrite channel, priority, message"
Unconditionally write the \fImessage\fR at the given \fIpriority\fR on \fIchannel\fR.
The channel can be one of \f(CW\*(C`debug\*(C'\fR, \f(CW\*(C`error\*(C'\fR or \f(CW\*(C`output\*(C'\fR.
.PP
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 \fIlogconfig()\fR routine
which takes the following switches, in alphabetical order:
.ie n .IP """\-caller"" => [ \fIparameters\fR ]" 4
.el .IP "\f(CW\-caller\fR => [ \fIparameters\fR ]" 4
.IX Item "-caller => [ parameters ]"
Request that caller information (relative to the \fIlogxxx()\fR call) be part
of the log message. The given \fIparameters\fR are handed off to the
creation routine of \f(CW\*(C`Log::Agent::Tag::Caller\*(C'\fR and are documented there.
.Sp
I usually say something like:
.Sp
.Vb 1
\& \-caller => [ \-display => \*(Aq($sub/$line)\*(Aq, \-postfix => 1 ]
.Ve
.Sp
which I find informative enough. On occasion, I found myself using more
complex sequences.  See Log::Agent::Tag::Caller.
.ie n .IP """\-confess"" => \fIflag\fR" 4
.el .IP "\f(CW\-confess\fR => \fIflag\fR" 4
.IX Item "-confess => flag"
When true, all \fIlogdie()\fR calls will be automatically masqueraded as
\&\fIlogconfess()\fR.
.ie n .IP """\-debug"" => \fIpriority or level\fR" 4
.el .IP "\f(CW\-debug\fR => \fIpriority or level\fR" 4
.IX Item "-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
\&\fB\s-1PRIORITIES AND LEVEL\s0\fR) for \fIlogdbg()\fR calls.
.Sp
Calls tagged with a level less than or equal to the given threshold will
pass through, others will return prematurely without logging anything.
.ie n .IP """\-driver"" => \fIdriver_object\fR" 4
.el .IP "\f(CW\-driver\fR => \fIdriver_object\fR" 4
.IX Item "-driver => driver_object"
This switch defines the driver object to be used, which must be an heir of
the \f(CW\*(C`Log::Agent::Driver\*(C'\fR class. See \fILog::Agent::Driver\fR\|(3) for a list
of the available drivers.
.ie n .IP """\-level"" => \fIpriority or level\fR" 4
.el .IP "\f(CW\-level\fR => \fIpriority or level\fR" 4
.IX Item "-level => priority or level"
Specifies both \f(CW\*(C`\-debug\*(C'\fR and \f(CW\*(C`\-trace\*(C'\fR levels at the same time, to a
common value.
.ie n .IP """\-prefix"" => \fIname\fR" 4
.el .IP "\f(CW\-prefix\fR => \fIname\fR" 4
.IX Item "-prefix => name"
Defines the application name which will be pre-pended to all messages,
followed by \f(CW": "\fR (a colon and a space). Using this switch alone will
configure the default driver to use that prefix (stripped down to its
basename component).
.Sp
When a driver object is used, the \f(CW\*(C`\-prefix\*(C'\fR switch is kept at the
\&\f(CW\*(C`Log::Agent\*(C'\fR level only and is not passed to the driver: it is up to
the driver's creation routine to request the \f(CW\*(C`\-prefix\*(C'\fR. 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.
.ie n .IP """\-priority"" => [ \fIparameters\fR ]" 4
.el .IP "\f(CW\-priority\fR => [ \fIparameters\fR ]" 4
.IX Item "-priority => [ parameters ]"
Request that message priority information be part of the log message.
The given \fIparameters\fR are handed off to the
creation routine of \f(CW\*(C`Log::Agent::Tag::Priority\*(C'\fR and are documented there.
.Sp
I usually say something like:
.Sp
.Vb 1
\&        \-priority => [ \-display => \*(Aq[$priority]\*(Aq ]
.Ve
.Sp
which will display the whole priority name at the beginning of the messages,
e.g. \*(L"[warning]\*(R" for a \fIlogwarn()\fR or \*(L"[error]\*(R" for \fIlogerr()\fR.
See Log::Agent::Tag::Priority and Log::Agent::Priorities.
.Sp
\&\fB\s-1NOTE\s0\fR: Using \f(CW\*(C`\-priority\*(C'\fR does not prevent the \f(CW\*(C`\-duperr\*(C'\fR 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.
.ie n .IP """\-tags"" => [ \fIlist of \fI""Log::Agent::Tag""\fI objects\fR ]" 4
.el .IP "\f(CW\-tags\fR => [ \fIlist of \f(CILog::Agent::Tag\fI objects\fR ]" 4
.IX Item "-tags => [ list of Log::Agent::Tag objects ]"
Specifies user-defined tags to be added to each message.  The objects
given here must inherit from \f(CW\*(C`Log::Agent::Tag\*(C'\fR and conform to its
interface.  See Log::Agent::Tag for details.
.Sp
At runtime, well after \fIlogconfig()\fR was issued, it may be desirable to
add (or remove) a user tag.  Use the \f(CW\*(C`logtags()\*(C'\fR routine for this purpose,
and iteract directly with the tag list object.
.Sp
For instance, a web module might wish to tag all the messages with a
session \s-1ID,\s0 information that might not have been available by the time
\&\fIlogconfig()\fR was issued.
.ie n .IP """\-trace"" => \fIpriority or level\fR" 4
.el .IP "\f(CW\-trace\fR => \fIpriority or level\fR" 4
.IX Item "-trace => priority or level"
Same a \f(CW\*(C`\-debug\*(C'\fR but applies to \fIlogsay()\fR, \fIlogwarn()\fR, \fIlogerr()\fR and \fIlogtrc()\fR.
.Sp
When unspecified, \f(CW\*(C`Log::Agent\*(C'\fR runs at the \*(L"notice\*(R" level.
.PP
Additional routines, not exported by default, are:
.IP "logtags" 4
.IX Item "logtags"
Returns a \f(CW\*(C`Log::Agent::Tag_List\*(C'\fR object, which holds all user-defined
tags that are to be added to each log message.
.Sp
The initial list of tags is normally supplied by the application at
\&\fIlogconfig()\fR time, via the \f(CW\*(C`\-tags\*(C'\fR 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.
.SH "KNOWN LIMITATIONS"
.IX Header "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. :\-)
.IP "\(bu" 4
A module which calls \fIlogdie()\fR may have its die trapped if called from
within an \fIeval()\fR, 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.
.IP "\(bu" 4
Some drivers lack customization and hardwire a few things that come
from my personal taste, like the prefixing done when \fIduperr\fR is set
in Log::Agent::Driver::File, or the fact that the \f(CW\*(C`debug\*(C'\fR and \f(CW\*(C`stderr\*(C'\fR
channels are merged as one in the Log::Agent::Driver::Default driver.
.IP "\(bu" 4
When using \fIlogcroak()\fR or \fIlogconfess()\fR, 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?
.SH "AUTHOR"
.IX Header "AUTHOR"
Log::Agent was originally authored by Raphael Manfredi \fI<Raphael_Manfredi@pobox.com>\fR and is currently maintained by Mark Rogaski \fI<mrogaski@cpan.org>\fR.
.SH "LICENSE"
.IX Header "LICENSE"
Copyright (c) 1999\-2000 Raphael Manfredi.
.PP
Copyright (c) 2002\-2003, 2005, 2013 Mark Rogaski; all rights reserved.
.PP
This module is free software.  You can redistribute it and/or
modify it under the terms of the Artistic License 2.0.
.PP
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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fILog::Agent::Driver\fR\|(3), \fICarp\fR\|(3).