| 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). |