1No::Worries::Log(3) User Contributed Perl Documentation No::Worries::Log(3)
2
6 No::Worries::Log - logging without worries
7
9 use No::Worries::Log qw(*);
10 # log an information level message with sprintf()-like syntax
12 log_info("accepted connection from %s:%d", inet_ntoa($addr), $port);
13 # log expensive debugging information only if needed
15 if (log_wants_debug()) {
16 $string = ... whatever ...
17 log_debug($string, { component => "webui" });
18 }
19 # 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 # specify the filter to use: debug messages from web* components
27 log_filter(<<EOT);
28 debug component=~^web
29 EOT
30
32 This module eases information logging by providing convenient functions
33 to log and filter information. All the functions die() on error.
34 It provides five main functions to submit information to be logged:
36 • log_error(ARGUMENTS): for error information
38 • log_warning(ARGUMENTS): for warning information
40 • log_info(ARGUMENTS): for (normal) information
42 • log_debug(ARGUMENTS): for debugging information
44 • log_trace(): for a low level trace
46 The supplied information is structured and can contain extra attributes
48 (key/value pairs) like in the SYNOPSIS example.
49 If the information passes through the filter, it is given to the
51 handler for logging.
52
54 An information "object" always contains the following attributes:
55 • "level": the information level as "error", "warning", "info",
57 "debug" or "trace"
58 • "time": Unix time indicating when the information got submitted
60 • "caller": the name of the caller's subroutine or "main"
62 • "file": the file path
64 • "line": the line number
66 • "program": the program name, as known by the No::Worries module
68 • "host": the host name, see $No::Worries::HostName
70 • "pid": the process identifier
72 • "tid": the thread identifier (in case threads are used)
74 • "message": the formatted message string
76 In addition, extra attributes can be given when calling log_error(),
78 log_warning(), log_info() or log_debug().
79 These attributes are mainly used for filtering (see next section) but
81 can also be used for formatting.
82
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 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 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 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 Here are commented examples:
107 # comments start with a 'hash' sign
109 # all info level
110 info
111 # debug level with messages matching "permission denied"
113 # (expressions are space separated so the space must be escaped)
114 debug message=~permission\x20denied
115 # debug level from any subroutine in Foo::Bar on host "venus"
117 debug caller=~^Foo::Bar:: host==venus
118 # trace level at the end of the file foo.pm
120 trace file=/full/path/foo.pm line>999
121 Note: user-supplied attributes can also be used in filters. If they are
123 not defined, the match will fail. For instance:
124 # 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 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 # multi-line style filter
138 info
139 debug caller==main
140 is equivalent to:
142 info or debug and caller==main
144
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 The default handler prints compact yet user friendly output to STDOUT
151 ("info" level) or STDERR (otherwise).
152 The No::Worries::Syslog module contains a similar handler to log
154 information to syslog.
155 Here is how to change the variable to a handler that dumps all the
157 information attributes to STDERR:
158 $No::Worries::Log::Handler = \&No::Worries::Log::log2dump;
160 The same can be achived at module loading time by using for instance:
162 use No::Worries::Log qw(* log2dump);
164 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
171 This module provides the following functions (none of them being
172 exported by default):
173 log_filter(FILTER)
175 use the given filter (string) to configure what should gets logged
176 or not
177 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 log_wants_error()
184 return true if the current filter may pass error level information
185 log_wants_warning()
187 return true if the current filter may pass warning level
188 information
189 log_wants_info()
191 return true if the current filter may pass info level information
192 log_wants_debug()
194 return true if the current filter may pass debug level information
195 log_wants_trace()
197 return true if the current filter may pass trace level information
198 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 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 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 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 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 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 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
231 log_error(), log_warning(), log_info() and log_debug() can be called in
232 different ways:
233 • log_xxx(): no arguments, same as giving an empty string
235 • log_xxx("string"): the message will be the given string
237 • log_xxx("format", @args): the message will be the result of
239 sprintf()
240 • log_xxx(\&code): the message will be the return value of the code
242 • log_xxx(\&code, @args): idem but also supplying arguments to give
244 In addition, in all cases, an optional last argument containing user-
246 supplied attributes can be given as a hash reference. For instance:
247 log_info("foo is %s", $foo, { component => "webui" });
249 Note that the following:
251 log_debug(\&dump_hash, \%big_hash);
253 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 log_debug(\&dump_hash, \%big_hash, {});
259 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 log_debug("unexpected data: %s [line %d]", $data, \"line");
265 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 # 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
289 This module uses the following global variables (none of them being
290 exported):
291 $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
298 This module uses the "NO_WORRIES" environment variable to find out
299 which handler to use by default. Supported values are:
300 "log2std"
302 use No::Worries::Log::log2std() (this is the default anyway)
303 "log2dump"
305 use No::Worries::Log::log2dump()
306
308 No::Worries, No::Worries::Syslog.
309
311 Lionel Cons <http://cern.ch/lionel.cons>
312 Copyright (C) CERN 2012-2019
314perl v5.38.0 2023-07-21 No::Worries::Log(3)