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 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 logsay "some trace message" if $verbose;
117 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 logwarn message
123 Log a warning message at the "warning" priority to the "error"
124 channel.
125 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 logerr message
131 Log an error message at the "error" priority to the "error"
132 channel.
133 logdie message
135 Log a fatal message at the "critical" priority to the "error"
136 channel, and then dies.
137 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 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 Log::Agent::inited
151 Returns true when "Log::Agent" was initialized, either explicitly
152 via a logconfig() or implicitely via any logxxx() call.
153 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 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 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 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 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 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 "-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 I usually say something like:
187 -caller => [ -display => '($sub/$line)', -postfix => 1 ]
189 which I find informative enough. On occasion, I found myself using
191 more complex sequences. See Log::Agent::Tag::Caller.
192 "-confess" => flag
194 When true, all logdie() calls will be automatically masqueraded as
195 logconfess().
196 "-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 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 "-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 "-level" => priority or level
212 Specifies both "-debug" and "-trace" levels at the same time, to a
213 common value.
214 "-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 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 "-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 I usually say something like:
234 -priority => [ -display => '[$priority]' ]
236 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 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 "-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 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 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 "-trace" => priority or level
261 Same a "-debug" but applies to logsay(), logwarn(), logerr() and
262 logtrc().
263 When unspecified, "Log::Agent" runs at the "notice" level.
265 Additional routines, not exported by default, are:
267 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 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
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 · 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 · 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 · 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
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
305 Copyright (c) 1999-2000 Raphael Manfredi.
306 Copyright (c) 2002-2003, 2005, 2013 Mark Rogaski; all rights reserved.
308 This module is free software. You can redistribute it and/or modify it
310 under the terms of the Artistic License 2.0.
311 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
317 Log::Agent::Driver(3), Carp(3).
318perl v5.32.1 2021-02-15 Agent(3)