Debian Codegraph @

README

raw
1 NAME
2 Log::Agent - logging agent
3
4 SYNOPSIS
5 use Log::Agent; # in all reusable components
6 logerr "error";
7 logtrc "notice:12", "notice that" if ...;
8 logdie "log and die";
9
10 use Log::Agent; # in application's main
11 logconfig(-prefix => $0); # simplest, uses default driver
12
13 use Log::Agent; # another more complex example
14 require Log::Agent::Driver::File; # logging made to file
15 logconfig(-driver =>
16 Log::Agent::Driver::File->make(
17 -prefix => $0,
18 -showpid => 1,
19 -channels => {
20 'error' => "$0.err",
21 'output' => "$0.out",
22 'debug' => "$0.dbg",
23 },
24 )
25 );
26
27 DESCRIPTION
28 The `Log::Agent' module provides an abstract layer for logging and
29 tracing, which is independant from the actual method used to physically
30 perform those activities. It acts as an agent (hence the name) that
31 collects the requests and delegates processing to a sublayer: the
32 logging driver.
33
34 The `Log::Agent' module is meant to be used in all reusable components,
35 since they cannot know in advance how the application which ends up
36 using them will perform its logging activities: either by emitting
37 messages on stdout and errors on stderr, or by directing messages to
38 logfiles, or by using syslog(3).
39
40 The logging interface is common for all the logging drivers, and is
41 therefore the result of a compromise between many logging schemes: any
42 information given at this level must be either handled by all drivers,
43 or may be ignored depending on the application's final choice.
44
45 PRIORITIES AND LEVEL
46 The `Log::Agent' module can use both priorities (as defined by
47 syslog(3)) or logging levels, or either, in which case there is an
48 implicit computation of the missing item (i.e. the level 4, for
49 instance, corresponds to the "warning" priority, and vice-versa). See
50 Log::Agent::Priorities for more details.
51
52 A logging level is defined as being a threshold: any level lesser than
53 or equal to that threshold will be logged.
54
55 At the `Log::Agent' level, it is possible to define a trace level and a
56 debug level. Only the messages below those levels (inclusive) will be
57 handed out to the underlying driver for logging. They are used by the
58 logtrc() and logdbg() routines, respectively.
59
60 CHANNELS
61 The `Log::Agent' class defines three logging channels, which are
62 `error', `output' and `debug'. Depending on the driver used for logging,
63 those channels are ignored (typically with syslog()) or may be
64 implicitely defined (default logging, i.e. the one achieved by the
65 `Log::Agent::Driver::Default' driver, remaps `error' and `debug' to
66 stderr, `output' to stdout).
67
68 INTERFACE
69 Anywhere a *message* is expected, it can be a single string, or a
70 printf()-like format string followed by the required arguments. The
71 special macro `%m' is handled directly by `Log::Agent' and is replaced
72 by the string version of $!, which is the last error message returned by
73 the last failing system call.
74
75 NOTE: There should not be any trailing "\n" in the *message* strings,
76 nor any embededed one, although this is not enforced. Remember that the
77 main purpose of `Log::Agent' is to specify logging messages in a
78 standard way! Therefore, most of the time, a "should" should be read as
79 "must" and "should not" as "must not", which is the strongest
80 interdiction form available in English, as far as I know.
81
82 Here are valid *message* examples:
83
84 "started since $time"
85 "started since %s", $time
86 "fork: %m"
87
88 The follwing logging interface is made available to modules:
89
90 logdbg *priority*, *message*
91 Debug logging of *message* to the `debug' channel.
92
93 You may specify any priority you want, i.e. a `debug' priority is
94 not enforced here. You may even specify `"notice:4"' if you wish, to
95 have the message logged if the debug level is set to 4 or less. If
96 handed over to syslog(3), the message will nonetheless be logged at
97 the `notice' priority.
98
99 logtrc *priority*, *message*
100 Trace logging of *message* to the `output' channel.
101
102 Like logdbg() above, you are not restricted to the `info' priority.
103 This routine checks the logging level (either explicit as in
104 `"info:14"' or implicit as in `"notice"') against the trace level.
105
106 logsay *message*
107 Log the message at the `notice' priority to the `output' channel.
108 The logging always takes place under the default `-trace' settings,
109 but only if the routine is called, naturally. This means you can
110 still say:
111
112 logsay "some trace message" if $verbose;
113
114 and control whether the message is emitted by using some external
115 configuration for your module (e.g. by adding a -verbose flag to the
116 creation routine of your class).
117
118 logwarn *message*
119 Log a warning message at the `warning' priority to the `error'
120 channel.
121
122 logcarp *message*
123 Same as logwarn(), but issues a Carp::carp(3) call instead, which
124 will warn from the perspective of the routine's caller.
125
126 logerr *message*
127 Log an error message at the `error' priority to the `error' channel.
128
129 logdie *message*
130 Log a fatal message at the `critical' priority to the `error'
131 channel, and then dies.
132
133 logconfess *message*
134 Same as logdie(), but issues a Carp::confess(3) call instead. It is
135 possible to configure the `Log::Agent' module via the `-confess'
136 switch to automatically redirect a logdie() to logconfess(), which
137 is invaluable during unit testing.
138
139 logcroak *message*
140 Same as logdie(), but issues a Carp::croak(3) call instead. It is
141 possible to configure the `Log::Agent' module via the `-confess'
142 switch to automatically redirect a logcroak() to logconfess(), which
143 is invaluable during unit testing.
144
145 Log::Agent::inited
146 Returns true when `Log::Agent' was initialized, either explicitely
147 via a logconfig() or implicitely via any logxxx() call.
148
149 Modules sometimes wish to report errors from the perspective of their
150 caller's caller, not really their caller. The following interface is
151 therefore provided:
152
153 logxcarp *offset*, *message*
154 Same a logcarp(), but with an additional offset to be applied on the
155 stack. To warn one level above your caller, set it to 1.
156
157 logxcroak *offset*, *message*
158 Same a logcroak(), but with an additional offset to be applied on
159 the stack. To report an error one level above your caller, set it to
160 1.
161
162 For applications that wish to implement a debug layer on top of
163 `Log::Agent', the following routine is provided. Note that it is not
164 imported by default, i.e. it needs to be explicitely mentionned at `use'
165 time, since it is not meant to be used directly under regular usage.
166
167 logwrite *channel*, *priority*, *message*
168 Unconditionally write the *message* at the given *priority* on
169 *channel*. The channel can be one of `debug', `error' or `output'.
170
171 At the application level, one needs to commit once and for all about the
172 logging scheme to be used. This is done thanks to the logconfig()
173 routine which takes the following switches, in alphabetical order:
174
175 `-caller' => [ *parameters* ]
176 Request that caller information (relative to the logxxx() call) be
177 part of the log message. The given *parameters* are handed off to
178 the creation routine of `Log::Agent::Tag::Caller' and are documented
179 there.
180
181 I usually say something like:
182
183 -caller => [ -display => '($sub/$line)', -postfix => 1 ]
184
185 which I find informative enough. On occasion, I found myself using
186 more complex sequences. See Log::Agent::Tag::Caller.
187
188 `-confess' => *flag*
189 When true, all logdie() calls will be automatically masqueraded as
190 logconfess().
191
192 `-debug' => *priority or level*
193 Sets the priority threshold (can be expressed as a string or a
194 number, the string being mapped to a logging level as described
195 above in PRIORITIES AND LEVEL) for logdbg() calls.
196
197 Calls tagged with a level less than or equal to the given threshold
198 will pass through, others will return prematurely without logging
199 anything.
200
201 `-driver' => *driver_object*
202 This switch defines the driver object to be used, which must be an
203 heir of the `Log::Agent::Driver' class. See Log::Agent::Driver(3)
204 for a list of the available drivers.
205
206 `-level' => *priority or level*
207 Specifies both `-debug' and `-trace' levels at the same time, to a
208 common value.
209
210 `-prefix' => *name*
211 Defines the application name which will be pre-pended to all
212 messages, followed by `": "' (a colon and a space). Using this
213 switch alone will configure the default driver to use that prefix
214 (stripped down to its basename component).
215
216 When a driver object is used, the `-prefix' switch is kept at the
217 `Log::Agent' level only and is not passed to the driver: it is up to
218 the driver's creation routine to request the `-prefix'. Having this
219 information in Log::Agent enables the module to die on critical
220 errors with that error prefix, since it cannot rely on the logging
221 driver for that, obviously.
222
223 `-priority' => [ *parameters* ]
224 Request that message priority information be part of the log
225 message. The given *parameters* are handed off to the creation
226 routine of `Log::Agent::Tag::Priority' and are documented there.
227
228 I usually say something like:
229
230 -priority => [ -display => '[$priority]' ]
231
232 which will display the whole priority name at the beginning of the
233 messages, e.g. "[warning]" for a logwarn() or "[error]" for
234 logerr(). See Log::Agent::Tag::Priority and Log::Agent::Priorities.
235
236 NOTE: Using `-priority' does not prevent the `-duperr' flag of the
237 file driver to also add its own hardwired prefixing in front of
238 duplicated error messages. The two options act at a different level.
239
240 `-tags' => [ *list of `Log::Agent::Tag' objects* ]
241 Specifies user-defined tags to be added to each message. The objects
242 given here must inherit from `Log::Agent::Tag' and conform to its
243 interface. See Log::Agent::Tag for details.
244
245 At runtime, well after logconfig() was issued, it may be desirable
246 to add (or remove) a user tag. Use the `logtags()' routine for this
247 purpose, and iteract directly with the tag list object.
248
249 For instance, a web module might wish to tag all the messages with a
250 session ID, information that might not have been available by the
251 time logconfig() was issued.
252
253 `-trace' => *priority or level*
254 Same a `-debug' but applies to logsay(), logwarn(), logerr() and
255 logtrc().
256
257 When unspecified, `Log::Agent' runs at the "notice" level.
258
259 Additional routines, not exported by default, are:
260
261 logtags
262 Returns a `Log::Agent::Tag_List' object, which holds all
263 user-defined tags that are to be added to each log message.
264
265 The initial list of tags is normally supplied by the application at
266 logconfig() time, via the `-tags' argument. To add or remove tags
267 after configuration time, one needs direct access to the tag list,
268 obtained via this routine. See Log::Agent::Tag_List for the
269 operations that can be performed.
270
271 KNOWN LIMITATIONS
272 The following limitations exist in this early version. They might be
273 addressed in future versions if they are perceived as annoying
274 limitatons instead of being just documented ones. :-)
275
276 * A module which calls logdie() may have its die trapped if called
277 from within an eval(), but unfortunately, the value of $@ is
278 unpredictable: it may be prefixed or not depending on the driver
279 used. This is harder to fix as one might think of at first glance.
280
281 * Some drivers lack customization and hardwire a few things that come
282 from my personal taste, like the prefixing done when *duperr* is set
283 in Log::Agent::Driver::File, or the fact that the `debug' and
284 `stderr' channels are merged as one in the
285 Log::Agent::Driver::Default driver.
286
287 * When using logcroak() or logconfess(), the place where the call was
288 made can still be visible when -caller is used, since the addition
289 of the caller information to the message is done before calling the
290 logging driver. Is this a problem?
291
292 AUTHOR
293 Log::Agent was originally authored by Raphael Manfredi
294 <[email protected]> and is currently maintained by Mark Rogaski
295 <[email protected]>.
296
297 LICENSE
298 Copyright (c) 1999-2000 Raphael Manfredi.
299
300 Copyright (c) 2002-2017 Mark Rogaski; all rights reserved.
301
302 This module is free software. You can redistribute it and/or modify it
303 under the terms of the Artistic License 2.0.
304
305 This program is distributed in the hope that it will be useful, but
306 without any warranty; without even the implied warranty of
307 merchantability or fitness for a particular purpose.
308
309 SEE ALSO
310 Log::Agent::Driver(3), Carp(3).