1Agent(3) User Contributed Perl Documentation Agent(3)
2
6 Log::Agent - logging agent
7
9 use Log::Agent; # in all reusable components
10 logerr "error";
11 logtrc "notice:12", "notice that" if ...;
12 logdie "log and die";
13 use Log::Agent; # in application's main
15 logconfig(-prefix => $0); # simplest, uses default driver
16 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
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 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 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
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 A logging level is defined as being a threshold: any level lesser than
57 or equal to that threshold will be logged.
58 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
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
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 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 Here are valid message examples:
87 "started since $time"
89 "started since %s", $time
90 "fork: %m"
91 The follwing logging interface is made available to modules:
93 logdbg priority, message
95 Debug logging of message to the "debug" channel.
96 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 logtrc priority, message
104 Trace logging of message to the "output" channel.
105 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 logdebug message
111 Log the message at the "debug" priority to the "output" channel.
112 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 loginfo message
118 Log the message at the "info" priority to the "output" channel.
119 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 logsay "some trace message" if $verbose;
127 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 logwarn message
133 Log a warning message at the "warning" priority to the "error"
134 channel.
135 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 logcluck message
141 Same as logwarn(), but dumps a full stacktrace as well.
142 logerr message
144 Log an error message at the "error" priority to the "error"
145 channel.
146 logdie message
148 Log a fatal message at the "critical" priority to the "error"
149 channel, and then dies.
150 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 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 Log::Agent::inited
164 Returns true when "Log::Agent" was initialized, either explicitly
165 via a logconfig() or implicitely via any logxxx() call.
166 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 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 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 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 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 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 "-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 I usually say something like:
200 -caller => [ -display => '($sub/$line)', -postfix => 1 ]
202 which I find informative enough. On occasion, I found myself using
204 more complex sequences. See Log::Agent::Tag::Caller.
205 "-confess" => flag
207 When true, all logdie() calls will be automatically masqueraded as
208 logconfess().
209 "-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 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 "-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 "-level" => priority or level
225 Specifies both "-debug" and "-trace" levels at the same time, to a
226 common value.
227 "-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 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 "-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 I usually say something like:
247 -priority => [ -display => '[$priority]' ]
249 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 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 "-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 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 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 "-trace" => priority or level
274 Same a "-debug" but applies to logsay(), logwarn(), logerr() and
275 logtrc().
276 When unspecified, "Log::Agent" runs at the "notice" level.
278 Additional routines, not exported by default, are:
280 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 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
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 • 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 • 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 • 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
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
318 Copyright (c) 1999-2000 Raphael Manfredi.
319 Copyright (c) 2002-2003, 2005, 2013 Mark Rogaski; all rights reserved.
321 This module is free software. You can redistribute it and/or modify it
323 under the terms of the Artistic License 2.0.
324 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
330 Log::Agent::Driver(3), Carp(3).
331perl v5.36.0 2023-01-20 Agent(3)