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       logdebug message
111           Log the message at the "debug" priority to the "output" channel.
112
113           The difference with logdbg() is twofold: logging is done on the
114           "output" channel, not the "debug" one, and the priority is
115           implicit.
116
117       loginfo message
118           Log the message at the "info" priority to the "output" channel.
119
120       logsay message
121           Log the message at the "notice" priority to the "output" channel.
122           The logging always takes place under the default "-trace" settings,
123           but only if the routine is called, naturally.  This means you can
124           still say:
125
126               logsay "some trace message" if $verbose;
127
128           and control whether the message is emitted by using some external
129           configuration for your module (e.g. by adding a -verbose flag to
130           the creation routine of your class).
131
132       logwarn message
133           Log a warning message at the "warning" priority to the "error"
134           channel.
135
136       logcarp message
137           Same as logwarn(), but issues a Carp::carp(3) call instead, which
138           will warn from the perspective of the routine's caller.
139
140       logcluck message
141           Same as logwarn(), but dumps a full stacktrace as well.
142
143       logerr message
144           Log an error message at the "error" priority to the "error"
145           channel.
146
147       logdie message
148           Log a fatal message at the "critical" priority to the "error"
149           channel, and then dies.
150
151       logconfess message
152           Same as logdie(), but issues a Carp::confess(3) call instead.  It
153           is possible to configure the "Log::Agent" module via the "-confess"
154           switch to automatically redirect a logdie() to logconfess(), which
155           is invaluable during unit testing.
156
157       logcroak message
158           Same as logdie(), but issues a Carp::croak(3) call instead.  It is
159           possible to configure the "Log::Agent" module via the "-confess"
160           switch to automatically redirect a logcroak() to logconfess(),
161           which is invaluable during unit testing.
162
163       Log::Agent::inited
164           Returns true when "Log::Agent" was initialized, either explicitly
165           via a logconfig() or implicitely via any logxxx() call.
166
167       Modules sometimes wish to report errors from the perspective of their
168       caller's caller, not really their caller.  The following interface is
169       therefore provided:
170
171       logxcarp offset, message
172           Same a logcarp(), but with an additional offset to be applied on
173           the stack.  To warn one level above your caller, set it to 1.
174
175       logxcroak offset, message
176           Same a logcroak(), but with an additional offset to be applied on
177           the stack.  To report an error one level above your caller, set it
178           to 1.
179
180       For applications that wish to implement a debug layer on top of
181       "Log::Agent", the following routine is provided.  Note that it is not
182       imported by default, i.e. it needs to be explicitly mentionned at "use"
183       time, since it is not meant to be used directly under regular usage.
184
185       logwrite channel, priority, message
186           Unconditionally write the message at the given priority on channel.
187           The channel can be one of "debug", "error" or "output".
188
189       At the application level, one needs to commit once and for all about
190       the logging scheme to be used. This is done thanks to the logconfig()
191       routine which takes the following switches, in alphabetical order:
192
193       "-caller" => [ parameters ]
194           Request that caller information (relative to the logxxx() call) be
195           part of the log message. The given parameters are handed off to the
196           creation routine of "Log::Agent::Tag::Caller" and are documented
197           there.
198
199           I usually say something like:
200
201            -caller => [ -display => '($sub/$line)', -postfix => 1 ]
202
203           which I find informative enough. On occasion, I found myself using
204           more complex sequences.  See Log::Agent::Tag::Caller.
205
206       "-confess" => flag
207           When true, all logdie() calls will be automatically masqueraded as
208           logconfess().
209
210       "-debug" => priority or level
211           Sets the priority threshold (can be expressed as a string or a
212           number, the string being mapped to a logging level as described
213           above in PRIORITIES AND LEVEL) for logdbg() calls.
214
215           Calls tagged with a level less than or equal to the given threshold
216           will pass through, others will return prematurely without logging
217           anything.
218
219       "-driver" => driver_object
220           This switch defines the driver object to be used, which must be an
221           heir of the "Log::Agent::Driver" class. See Log::Agent::Driver(3)
222           for a list of the available drivers.
223
224       "-level" => priority or level
225           Specifies both "-debug" and "-trace" levels at the same time, to a
226           common value.
227
228       "-prefix" => name
229           Defines the application name which will be pre-pended to all
230           messages, followed by ": " (a colon and a space). Using this switch
231           alone will configure the default driver to use that prefix
232           (stripped down to its basename component).
233
234           When a driver object is used, the "-prefix" switch is kept at the
235           "Log::Agent" level only and is not passed to the driver: it is up
236           to the driver's creation routine to request the "-prefix". Having
237           this information in Log::Agent enables the module to die on
238           critical errors with that error prefix, since it cannot rely on the
239           logging driver for that, obviously.
240
241       "-priority" => [ parameters ]
242           Request that message priority information be part of the log
243           message.  The given parameters are handed off to the creation
244           routine of "Log::Agent::Tag::Priority" and are documented there.
245
246           I usually say something like:
247
248                   -priority => [ -display => '[$priority]' ]
249
250           which will display the whole priority name at the beginning of the
251           messages, e.g. "[warning]" for a logwarn() or "[error]" for
252           logerr().  See Log::Agent::Tag::Priority and
253           Log::Agent::Priorities.
254
255           NOTE: Using "-priority" does not prevent the "-duperr" flag of the
256           file driver to also add its own hardwired prefixing in front of
257           duplicated error messages.  The two options act at a different
258           level.
259
260       "-tags" => [ list of "Log::Agent::Tag" objects ]
261           Specifies user-defined tags to be added to each message.  The
262           objects given here must inherit from "Log::Agent::Tag" and conform
263           to its interface.  See Log::Agent::Tag for details.
264
265           At runtime, well after logconfig() was issued, it may be desirable
266           to add (or remove) a user tag.  Use the logtags() routine for this
267           purpose, and iteract directly with the tag list object.
268
269           For instance, a web module might wish to tag all the messages with
270           a session ID, information that might not have been available by the
271           time logconfig() was issued.
272
273       "-trace" => priority or level
274           Same a "-debug" but applies to logsay(), logwarn(), logerr() and
275           logtrc().
276
277           When unspecified, "Log::Agent" runs at the "notice" level.
278
279       Additional routines, not exported by default, are:
280
281       logtags
282           Returns a "Log::Agent::Tag_List" object, which holds all user-
283           defined tags that are to be added to each log message.
284
285           The initial list of tags is normally supplied by the application at
286           logconfig() time, via the "-tags" argument.  To add or remove tags
287           after configuration time, one needs direct access to the tag list,
288           obtained via this routine.  See Log::Agent::Tag_List for the
289           operations that can be performed.
290

KNOWN LIMITATIONS

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

AUTHOR

313       Log::Agent was originally authored by Raphael Manfredi
314       <Raphael_Manfredi@pobox.com> and is currently maintained by Mark
315       Rogaski <mrogaski@cpan.org>.
316

LICENSE

318       Copyright (c) 1999-2000 Raphael Manfredi.
319
320       Copyright (c) 2002-2003, 2005, 2013 Mark Rogaski; all rights reserved.
321
322       This module is free software.  You can redistribute it and/or modify it
323       under the terms of the Artistic License 2.0.
324
325       This program is distributed in the hope that it will be useful, but
326       without any warranty; without even the implied warranty of
327       merchantability or fitness for a particular purpose.
328

SEE ALSO

330       Log::Agent::Driver(3), Carp(3).
331
332
333
334perl v5.36.0                      2023-01-20                          Agent(3)
Impressum