1Agent(3)              User Contributed Perl Documentation             Agent(3)
2
3
4

NAME

6       Log::Agent - logging agent
7

SYNOPSIS

9        use Log::Agent;            # in all reusable components
10        logerr "error";
11        logtrc "notice:12", "notice that" if ...;
12        logdie "log and die";
13
14        use Log::Agent;            # in application's main
15        logconfig(-prefix => $0);  # simplest, uses default driver
16
17        use Log::Agent;                    # another more complex example
18        require Log::Agent::Driver::File;  # logging made to file
19        logconfig(-driver =>
20            Log::Agent::Driver::File->make(
21                -prefix      => $0,
22                -showpid     => 1,
23                -channels    => {
24                    'error'  => "$0.err",
25                    'output' => "$0.out",
26                    'debug'  => "$0.dbg",
27                },
28            )
29        );
30

DESCRIPTION

32       The "Log::Agent" module provides an abstract layer for logging and
33       tracing, which is independent from the actual method used to physically
34       perform those activities. It acts as an agent (hence the name) that
35       collects the requests and delegates processing to a sublayer: the
36       logging driver.
37
38       The "Log::Agent" module is meant to be used in all reusable components,
39       since they cannot know in advance how the application which ends up
40       using them will perform its logging activities: either by emitting
41       messages on stdout and errors on stderr, or by directing messages to
42       logfiles, or by using syslog(3).
43
44       The logging interface is common for all the logging drivers, and is
45       therefore the result of a compromise between many logging schemes: any
46       information given at this level must be either handled by all drivers,
47       or may be ignored depending on the application's final choice.
48

PRIORITIES AND LEVEL

50       The "Log::Agent" module can use both priorities (as defined by
51       syslog(3)) or logging levels, or either, in which case there is an
52       implicit computation of the missing item (i.e. the level 4, for
53       instance, corresponds to the "warning" priority, and vice-versa).  See
54       Log::Agent::Priorities for more details.
55
56       A logging level is defined as being a threshold: any level lesser than
57       or equal to that threshold will be logged.
58
59       At the "Log::Agent" level, it is possible to define a trace level and a
60       debug level. Only the messages below those levels (inclusive) will be
61       handed out to the underlying driver for logging. They are used by the
62       logtrc() and logdbg() routines, respectively.
63

CHANNELS

65       The "Log::Agent" class defines three logging channels, which are
66       "error", "output" and "debug". Depending on the driver used for
67       logging, those channels are ignored (typically with syslog()) or may be
68       implicitely defined (default logging, i.e. the one achieved by the
69       "Log::Agent::Driver::Default" driver, remaps "error" and "debug" to
70       stderr, "output" to stdout).
71

INTERFACE

73       Anywhere a message is expected, it can be a single string, or a
74       printf()-like format string followed by the required arguments. The
75       special macro %m is handled directly by "Log::Agent" and is replaced by
76       the string version of $!, which is the last error message returned by
77       the last failing system call.
78
79       NOTE: There should not be any trailing "\n" in the message strings, nor
80       any embededed one, although this is not enforced. Remember that the
81       main purpose of "Log::Agent" is to specify logging messages in a
82       standard way!  Therefore, most of the time, a "should" should be read
83       as "must" and "should not" as "must not", which is the strongest
84       interdiction form available in English, as far as I know.
85
86       Here are valid message examples:
87
88           "started since $time"
89           "started since %s", $time
90           "fork: %m"
91
92       The follwing logging interface is made available to modules:
93
94       logdbg priority, message
95           Debug logging of message to the "debug" channel.
96
97           You may specify any priority you want, i.e.  a "debug" priority is
98           not enforced here. You may even specify "notice:4" if you wish, to
99           have the message logged if the debug level is set to 4 or less.  If
100           handed over to syslog(3), the message will nonetheless be logged at
101           the "notice" priority.
102
103       logtrc priority, message
104           Trace logging of message to the "output" channel.
105
106           Like logdbg() above, you are not restricted to the "info" priority.
107           This routine checks the logging level (either explicit as in
108           "info:14" or implicit as in "notice") against the trace level.
109
110       logsay message
111           Log the message at the "notice" priority to the "output" channel.
112           The logging always takes place under the default "-trace" settings,
113           but only if the routine is called, naturally.  This means you can
114           still say:
115
116               logsay "some trace message" if $verbose;
117
118           and control whether the message is emitted by using some external
119           configuration for your module (e.g. by adding a -verbose flag to
120           the creation routine of your class).
121
122       logwarn message
123           Log a warning message at the "warning" priority to the "error"
124           channel.
125
126       logcarp message
127           Same as logwarn(), but issues a Carp::carp(3) call instead, which
128           will warn from the perspective of the routine's caller.
129
130       logerr message
131           Log an error message at the "error" priority to the "error"
132           channel.
133
134       logdie message
135           Log a fatal message at the "critical" priority to the "error"
136           channel, and then dies.
137
138       logconfess message
139           Same as logdie(), but issues a Carp::confess(3) call instead.  It
140           is possible to configure the "Log::Agent" module via the "-confess"
141           switch to automatically redirect a logdie() to logconfess(), which
142           is invaluable during unit testing.
143
144       logcroak message
145           Same as logdie(), but issues a Carp::croak(3) call instead.  It is
146           possible to configure the "Log::Agent" module via the "-confess"
147           switch to automatically redirect a logcroak() to logconfess(),
148           which is invaluable during unit testing.
149
150       Log::Agent::inited
151           Returns true when "Log::Agent" was initialized, either explicitly
152           via a logconfig() or implicitely via any logxxx() call.
153
154       Modules sometimes wish to report errors from the perspective of their
155       caller's caller, not really their caller.  The following interface is
156       therefore provided:
157
158       logxcarp offset, message
159           Same a logcarp(), but with an additional offset to be applied on
160           the stack.  To warn one level above your caller, set it to 1.
161
162       logxcroak offset, message
163           Same a logcroak(), but with an additional offset to be applied on
164           the stack.  To report an error one level above your caller, set it
165           to 1.
166
167       For applications that wish to implement a debug layer on top of
168       "Log::Agent", the following routine is provided.  Note that it is not
169       imported by default, i.e. it needs to be explicitly mentionned at "use"
170       time, since it is not meant to be used directly under regular usage.
171
172       logwrite channel, priority, message
173           Unconditionally write the message at the given priority on channel.
174           The channel can be one of "debug", "error" or "output".
175
176       At the application level, one needs to commit once and for all about
177       the logging scheme to be used. This is done thanks to the logconfig()
178       routine which takes the following switches, in alphabetical order:
179
180       "-caller" => [ parameters ]
181           Request that caller information (relative to the logxxx() call) be
182           part of the log message. The given parameters are handed off to the
183           creation routine of "Log::Agent::Tag::Caller" and are documented
184           there.
185
186           I usually say something like:
187
188            -caller => [ -display => '($sub/$line)', -postfix => 1 ]
189
190           which I find informative enough. On occasion, I found myself using
191           more complex sequences.  See Log::Agent::Tag::Caller.
192
193       "-confess" => flag
194           When true, all logdie() calls will be automatically masqueraded as
195           logconfess().
196
197       "-debug" => priority or level
198           Sets the priority threshold (can be expressed as a string or a
199           number, the string being mapped to a logging level as described
200           above in PRIORITIES AND LEVEL) for logdbg() calls.
201
202           Calls tagged with a level less than or equal to the given threshold
203           will pass through, others will return prematurely without logging
204           anything.
205
206       "-driver" => driver_object
207           This switch defines the driver object to be used, which must be an
208           heir of the "Log::Agent::Driver" class. See Log::Agent::Driver(3)
209           for a list of the available drivers.
210
211       "-level" => priority or level
212           Specifies both "-debug" and "-trace" levels at the same time, to a
213           common value.
214
215       "-prefix" => name
216           Defines the application name which will be pre-pended to all
217           messages, followed by ": " (a colon and a space). Using this switch
218           alone will configure the default driver to use that prefix
219           (stripped down to its basename component).
220
221           When a driver object is used, the "-prefix" switch is kept at the
222           "Log::Agent" level only and is not passed to the driver: it is up
223           to the driver's creation routine to request the "-prefix". Having
224           this information in Log::Agent enables the module to die on
225           critical errors with that error prefix, since it cannot rely on the
226           logging driver for that, obviously.
227
228       "-priority" => [ parameters ]
229           Request that message priority information be part of the log
230           message.  The given parameters are handed off to the creation
231           routine of "Log::Agent::Tag::Priority" and are documented there.
232
233           I usually say something like:
234
235                   -priority => [ -display => '[$priority]' ]
236
237           which will display the whole priority name at the beginning of the
238           messages, e.g. "[warning]" for a logwarn() or "[error]" for
239           logerr().  See Log::Agent::Tag::Priority and
240           Log::Agent::Priorities.
241
242           NOTE: Using "-priority" does not prevent the "-duperr" flag of the
243           file driver to also add its own hardwired prefixing in front of
244           duplicated error messages.  The two options act at a different
245           level.
246
247       "-tags" => [ list of "Log::Agent::Tag" objects ]
248           Specifies user-defined tags to be added to each message.  The
249           objects given here must inherit from "Log::Agent::Tag" and conform
250           to its interface.  See Log::Agent::Tag for details.
251
252           At runtime, well after logconfig() was issued, it may be desirable
253           to add (or remove) a user tag.  Use the "logtags()" routine for
254           this purpose, and iteract directly with the tag list object.
255
256           For instance, a web module might wish to tag all the messages with
257           a session ID, information that might not have been available by the
258           time logconfig() was issued.
259
260       "-trace" => priority or level
261           Same a "-debug" but applies to logsay(), logwarn(), logerr() and
262           logtrc().
263
264           When unspecified, "Log::Agent" runs at the "notice" level.
265
266       Additional routines, not exported by default, are:
267
268       logtags
269           Returns a "Log::Agent::Tag_List" object, which holds all user-
270           defined tags that are to be added to each log message.
271
272           The initial list of tags is normally supplied by the application at
273           logconfig() time, via the "-tags" argument.  To add or remove tags
274           after configuration time, one needs direct access to the tag list,
275           obtained via this routine.  See Log::Agent::Tag_List for the
276           operations that can be performed.
277

KNOWN LIMITATIONS

279       The following limitations exist in this early version. They might be
280       addressed in future versions if they are perceived as annoying
281       limitatons instead of being just documented ones. :-)
282
283       ·   A module which calls logdie() may have its die trapped if called
284           from within an eval(), but unfortunately, the value of $@ is
285           unpredictable: it may be prefixed or not depending on the driver
286           used. This is harder to fix as one might think of at first glance.
287
288       ·   Some drivers lack customization and hardwire a few things that come
289           from my personal taste, like the prefixing done when duperr is set
290           in Log::Agent::Driver::File, or the fact that the "debug" and
291           "stderr" channels are merged as one in the
292           Log::Agent::Driver::Default driver.
293
294       ·   When using logcroak() or logconfess(), the place where the call was
295           made can still be visible when -caller is used, since the addition
296           of the caller information to the message is done before calling the
297           logging driver.  Is this a problem?
298

AUTHOR

300       Log::Agent was originally authored by Raphael Manfredi
301       <Raphael_Manfredi@pobox.com> and is currently maintained by Mark
302       Rogaski <mrogaski@cpan.org>.
303

LICENSE

305       Copyright (c) 1999-2000 Raphael Manfredi.
306
307       Copyright (c) 2002-2003, 2005, 2013 Mark Rogaski; all rights reserved.
308
309       This module is free software.  You can redistribute it and/or modify it
310       under the terms of the Artistic License 2.0.
311
312       This program is distributed in the hope that it will be useful, but
313       without any warranty; without even the implied warranty of
314       merchantability or fitness for a particular purpose.
315

SEE ALSO

317       Log::Agent::Driver(3), Carp(3).
318
319
320
321perl v5.30.1                      2020-01-30                          Agent(3)
Impressum