1No::Worries::Log(3)   User Contributed Perl Documentation  No::Worries::Log(3)
2
3
4

NAME

6       No::Worries::Log - logging without worries
7

SYNOPSIS

9         use No::Worries::Log qw(*);
10
11         # log an information level message with sprintf()-like syntax
12         log_info("accepted connection from %s:%d", inet_ntoa($addr), $port);
13
14         # log expensive debugging information only if needed
15         if (log_wants_debug()) {
16             $string = ... whatever ...
17             log_debug($string, { component => "webui" });
18         }
19
20         # log a low-level trace: this is cheap and can be added in many places
21         sub foo () {
22             log_trace();
23             ... code...
24         }
25
26         # specify the filter to use: debug messages from web* components
27         log_filter(<<EOT);
28             debug component=~^web
29         EOT
30

DESCRIPTION

32       This module eases information logging by providing convenient functions
33       to log and filter information. All the functions die() on error.
34
35       It provides five main functions to submit information to be logged:
36
37       •   log_error(ARGUMENTS): for error information
38
39       •   log_warning(ARGUMENTS): for warning information
40
41       •   log_info(ARGUMENTS): for (normal) information
42
43       •   log_debug(ARGUMENTS): for debugging information
44
45log_trace(): for a low level trace
46
47       The supplied information is structured and can contain extra attributes
48       (key/value pairs) like in the SYNOPSIS example.
49
50       If the information passes through the filter, it is given to the
51       handler for logging.
52

ATTRIBUTES

54       An information "object" always contains the following attributes:
55
56       •   "level": the information level as "error", "warning", "info",
57           "debug" or "trace"
58
59       •   "time": Unix time indicating when the information got submitted
60
61       •   "caller": the name of the caller's subroutine or "main"
62
63       •   "file": the file path
64
65       •   "line": the line number
66
67       •   "program": the program name, as known by the No::Worries module
68
69       •   "host": the host name, see $No::Worries::HostName
70
71       •   "pid": the process identifier
72
73       •   "tid": the thread identifier (in case threads are used)
74
75       •   "message": the formatted message string
76
77       In addition, extra attributes can be given when calling log_error(),
78       log_warning(), log_info() or log_debug().
79
80       These attributes are mainly used for filtering (see next section) but
81       can also be used for formatting.
82

FILTER

84       The filter defines which information should be logged (i.e. given to
85       the handler) or not. It can be controlled via the log_filter() and
86       log_configure() functions.
87
88       The filter is described via a multi-line string. Each line is made of
89       one or more space separated expressions that must be all true. A filter
90       matches if any of its lines matches. Empty lines and comments are
91       allowed for readability.
92
93       A filter expression can be either "error", "warning", "info", "debug"
94       or "trace" (meaning that the level must match it) or of the form
95       {attr}{op}{value} where {attr} is the attribute name, {op} is the
96       operation (either "=~", "!~", "==", "!=", "<", "<=", ">" or ">=") and
97       value is the value to use for the test (either an integer, a string or
98       a regular expression).
99
100       If the value is not an integer, it will be treated like the contents of
101       a double quoted string or a regular expression, so escape sequences
102       will be honored. For parsing reasons (expressions are space separated),
103       the value cannot contain space characters. If you need some, they have
104       to be escaped like in the examples below.
105
106       Here are commented examples:
107
108         # comments start with a 'hash' sign
109         # all info level
110         info
111
112         # debug level with messages matching "permission denied"
113         # (expressions are space separated so the space must be escaped)
114         debug message=~permission\x20denied
115
116         # debug level from any subroutine in Foo::Bar on host "venus"
117         debug caller=~^Foo::Bar:: host==venus
118
119         # trace level at the end of the file foo.pm
120         trace file=/full/path/foo.pm line>999
121
122       Note: user-supplied attributes can also be used in filters. If they are
123       not defined, the match will fail. For instance:
124
125         # we want to see only debug messages with a low karma
126         log_filter("debug karma<=42");
127         # the following will be logged
128         log_debug("yes", { karma => 7 });
129         # the following will not be logged
130         log_debug("no", { karma => 1999 });
131         log_debug("no");
132
133       You can also use an alternative syntax with explicit "or" and "and".
134       This is very convenient to fit the filter in a single line (for
135       instance when given on the command line). For instance:
136
137         # multi-line style filter
138         info
139         debug caller==main
140
141       is equivalent to:
142
143         info or debug and caller==main
144

HANDLER

146       If the information successfully passes through the filter it is given
147       to the handler, i.e. the code reference stored in
148       $No::Worries::Log::Handler.
149
150       The default handler prints compact yet user friendly output to STDOUT
151       ("info" level) or STDERR (otherwise).
152
153       The No::Worries::Syslog module contains a similar handler to log
154       information to syslog.
155
156       Here is how to change the variable to a handler that dumps all the
157       information attributes to STDERR:
158
159         $No::Worries::Log::Handler = \&No::Worries::Log::log2dump;
160
161       The same can be achived at module loading time by using for instance:
162
163         use No::Worries::Log qw(* log2dump);
164
165       You can put your own code in $No::Worries::Log::Handler. It will be
166       called with a single argument: the structured information as a hash
167       reference. This can be useful for ad-hoc filtering or to do something
168       else that logging to STDOUT/STDERR or syslog.
169

FUNCTIONS

171       This module provides the following functions (none of them being
172       exported by default):
173
174       log_filter(FILTER)
175           use the given filter (string) to configure what should gets logged
176           or not
177
178       log_configure(PATH)
179           use the given path (file) to configure what should gets logged or
180           not; this reads the file if needed (i.e. if it changed since last
181           time) and calls log_filter()
182
183       log_wants_error()
184           return true if the current filter may pass error level information
185
186       log_wants_warning()
187           return true if the current filter may pass warning level
188           information
189
190       log_wants_info()
191           return true if the current filter may pass info level information
192
193       log_wants_debug()
194           return true if the current filter may pass debug level information
195
196       log_wants_trace()
197           return true if the current filter may pass trace level information
198
199       log_error(ARGUMENTS)
200           give an error level information to the module to get logged if the
201           current filter lets it pass; see below for its ARGUMENTS
202
203       log_warning(ARGUMENTS)
204           give a warning level information to the module to get logged if the
205           current filter lets it pass; see below for its ARGUMENTS
206
207       log_info(ARGUMENTS)
208           give an info level information to the module to get logged if the
209           current filter lets it pass; see below for its ARGUMENTS
210
211       log_debug(ARGUMENTS)
212           give a debug level information to the module to get logged if the
213           current filter lets it pass; see below for its ARGUMENTS
214
215       log_trace()
216           give a trace level information to the module to get logged if the
217           current filter lets it pass; the trace information contains the
218           name of the caller subroutine, the file path and the line number
219
220       log2std(INFO)
221           handler for $No::Worries::Log::Handler to send information to
222           STDOUT/STDERR in a compact yet user friendly way; this is not
223           exported and must be called explicitly
224
225       log2dump(INFO)
226           handler for $No::Worries::Log::Handler that dumps all the
227           information attributes to STDERR; this is not exported and must be
228           called explicitly
229

USAGE

231       log_error(), log_warning(), log_info() and log_debug() can be called in
232       different ways:
233
234log_xxx(): no arguments, same as giving an empty string
235
236       •   log_xxx("string"): the message will be the given string
237
238       •   log_xxx("format", @args): the message will be the result of
239           sprintf()
240
241       •   log_xxx(\&code): the message will be the return value of the code
242
243       •   log_xxx(\&code, @args): idem but also supplying arguments to give
244
245       In addition, in all cases, an optional last argument containing user-
246       supplied attributes can be given as a hash reference. For instance:
247
248         log_info("foo is %s", $foo, { component => "webui" });
249
250       Note that the following:
251
252         log_debug(\&dump_hash, \%big_hash);
253
254       will treat the last argument as being the attributes hash. If this is
255       not what you want, you should supply an empty attributes hash so that
256       \%big_hash gets interpreted as an argument to give to dump_hash():
257
258         log_debug(\&dump_hash, \%big_hash, {});
259
260       With the sprintf() style usage, you can supply string references as
261       arguments. They will be replaced by the corresponding attributes. For
262       instance:
263
264         log_debug("unexpected data: %s [line %d]", $data, \"line");
265
266       The usages with a code reference are useful for expensive operations
267       that you want to perform only when you are pretty sure that the
268       information will be logged. The code reference will be called only
269       after an initial filtering. For instance:
270
271         # expensive code to return a message to maybe log
272         sub dump_state ($) {
273             my($data) = @_;
274             ... heavy work ...
275             return(... something ...);
276         }
277         # subroutine that may want to dump its state
278         sub foo () {
279             ... some code ...
280             log_debug(\&dump_state, $some_data);
281             ... some code ...
282         }
283         # filter that only cares about debug information from main::bar
284         log_filter("debug caller==main::bar");
285         # the following will not call dump_state()
286         foo();
287

GLOBAL VARIABLES

289       This module uses the following global variables (none of them being
290       exported):
291
292       $Handler
293           the subroutine (code reference) to call for every information that
294           successfully passes through the filter, the default is normally
295           \&No::Worries::Log::log2std() (see below)
296

ENVIRONMENT VARIABLES

298       This module uses the "NO_WORRIES" environment variable to find out
299       which handler to use by default. Supported values are:
300
301       "log2std"
302           use No::Worries::Log::log2std() (this is the default anyway)
303
304       "log2dump"
305           use No::Worries::Log::log2dump()
306

SEE ALSO

308       No::Worries, No::Worries::Syslog.
309

AUTHOR

311       Lionel Cons <http://cern.ch/lionel.cons>
312
313       Copyright (C) CERN 2012-2019
314
315
316
317perl v5.38.0                      2023-07-21               No::Worries::Log(3)
Impressum