1Log::Dispatchouli(3) User Contributed Perl Documentation Log::Dispatchouli(3)
2
6 Log::Dispatchouli - a simple wrapper around Log::Dispatch
7
9 version 3.006
10
12 my $logger = Log::Dispatchouli->new({
13 ident => 'stuff-purger',
14 facility => 'daemon',
15 to_stdout => $opt->{print},
16 debug => $opt->{verbose}
17 });
18 $logger->log([ "There are %s items left to purge...", $stuff_left ]);
20 $logger->log_debug("this is extra often-ignored debugging log");
22 $logger->log_fatal("Now we will die!!");
24
26 Log::Dispatchouli is a thin layer above Log::Dispatch and meant to make
27 it dead simple to add logging to a program without having to think much
28 about categories, facilities, levels, or things like that. It is meant
29 to make logging just configurable enough that you can find the logs you
30 want and just easy enough that you will actually log things.
31 Log::Dispatchouli can log to syslog (if you specify a facility),
33 standard error or standard output, to a file, or to an array in memory.
34 That last one is mostly useful for testing.
35 In addition to providing as simple a way to get a handle for logging
37 operations, Log::Dispatchouli uses String::Flogger to process the
38 things to be logged, meaning you can easily log data structures.
39 Basically: strings are logged as is, arrayrefs are taken as (sprintf
40 format, args), and subroutines are called only if needed. For more
41 information read the String::Flogger docs.
42
44 This library should run on perls released even a long time ago. It
45 should work on any version of perl released in the last five years.
46 Although it may work on older versions of perl, no guarantee is made
48 that the minimum required version will not be increased. The version
49 may be increased for any reason, and there is no promise that patches
50 will be accepted to lower the minimum required perl.
51
53 new
54 my $logger = Log::Dispatchouli->new(\%arg);
55 This returns a new logger, a Log::Dispatchouli object.
57 Valid arguments are:
59 ident - the name of the thing logging (mandatory)
61 to_self - log to the logger object for testing; default: false
62 to_stdout - log to STDOUT; default: false
63 to_stderr - log to STDERR; default: false
64 facility - to which syslog facility to send logs; default: none
65 to_file - log to PROGRAM_NAME.YYYYMMDD in the log path; default: false
67 log_file - a leaf name for the file to log to with to_file
68 log_path - path in which to log to file; defaults to DISPATCHOULI_PATH
69 environment variable or, failing that, to your system's tmpdir
70 file_format - this optional coderef is passed the message to be logged
72 and returns the text to write out
73 log_pid - if true, prefix all log entries with the pid; default: true
75 fail_fatal - a boolean; if true, failure to log is fatal; default: true
76 muted - a boolean; if true, only fatals are logged; default: false
77 debug - a boolean; if true, log_debug method is not a no-op
78 defaults to the truth of the DISPATCHOULI_DEBUG env var
79 quiet_fatal - 'stderr' or 'stdout' or an arrayref of zero, one, or both
80 fatal log messages will not be logged to these
81 (default: stderr)
82 config_id - a name for this logger's config; rarely needed!
83 syslog_socket - a value for Sys::Syslog's "socket" arg; default: "native"
84 The log path is either /tmp or the value of the DISPATCHOULI_PATH env
86 var.
87 If the DISPATCHOULI_NOSYSLOG env var is true, we don't log to syslog.
89 log
91 $logger->log(@messages);
92 $logger->log(\%arg, @messages);
94 This method uses String::Flogger on the input, then unconditionally
96 logs the result. Each message is flogged individually, then joined
97 with spaces.
98 If the first argument is a hashref, it will be used as extra arguments
100 to logging. It may include a "prefix" entry to preprocess the message
101 by prepending a string (if the prefix is a string) or calling a
102 subroutine to generate a new message (if the prefix is a coderef).
103 log_fatal
105 This behaves like the "log" method, but will throw the logged string as
106 an exception after logging.
107 This method can also be called as "fatal", to match other popular
109 logging interfaces. If you want to override this method, you must
110 override "log_fatal" and not "fatal".
111 log_debug
113 This behaves like the "log" method, but will only log (at the debug
114 level) if the logger object has its debug property set to true.
115 This method can also be called as "debug", to match other popular
117 logging interfaces. If you want to override this method, you must
118 override "log_debug" and not "debug".
119 log_event
121 This method is like "log", but is used for structured logging instead
122 of free form text. It's invoked like this:
123 $logger->log($event_type => $data_ref);
125 $event_type should be a simple string, probably a valid identifier,
127 that identifies the kind of event being logged. It is suggested, but
128 not required, that all events of the same type have the same kind of
129 structured data in them.
130 $data_ref is a set of key/value pairs of data to log in this event. It
132 can be an arrayref (in which case the ordering of pairs is preserved)
133 or a hashref (in which case they are sorted by key).
134 The logged string will be in logfmt format, meaning a series of
136 key=value pairs separated by spaces and following these rules:
137 • an "identifier" is a string of printable ASCII characters between
139 "!" and "~", excluding "\" and "="
140 • keys must be valid identifiers
142 • if a key is empty, "~" is used instead
144 • if a key contains characters not permitted in an identifier, they
146 are replaced by "?"
147 • values must either be valid identifiers, or be quoted
149 • quoted value start and end with """
151 • in a quoted value, """ becomes "\"", "\" becomes "\\", newline and
153 carriage return become "\n" and "\r" respectively, and other
154 control characters are replaced with "\u{....}" where the contents
155 of the braces are the hex value of the control character
156 When values are undef, they are represented as "~".
158 When values are array references, the index/values are mapped over, so
160 that:
161 key => [ 'a', 'b' ]
163 becomes
165 key.0=a key.1=b
167 When values are hash references, the key/values are mapped, with keys
169 sorted, so that:
170 key => { b => 2, a => 1 }
172 becomes
174 key.a=1 key.b=2
176 This expansion is performed recursively. If a value itself recurses,
178 appearances of a reference after the first time will be replaced with a
179 string like "&foo.bar", pointing to the first occurrence. This is not
180 meant to be a robust serialization mechanism. It's just here to help
181 you be a little lazy. Don't push the limits.
182 If the value in $data_ref is a code reference, it will be called and
184 its result logged. If its result is also a code reference, you get
185 whatever garbage that code reference stringifies to.
186 If the value in $data_ref is a reference reference, then the referenced
188 scalar will be passed to String::Flogger, and the resulting string will
189 be used as the value to log. That string will be quoted as described
190 above, if needed.
191 log_debug_event
193 This method is just like "log_event", but will log nothing unless the
194 logger has its "debug" property set to true.
195 set_debug
197 $logger->set_debug($bool);
198 This sets the logger's debug property, which affects the behavior of
200 "log_debug".
201 get_debug
203 This gets the logger's debug property, which affects the behavior of
204 "log_debug".
205 clear_debug
207 This method does nothing, and is only useful for
208 Log::Dispatchouli::Proxy objects. See Methods for Proxy Loggers,
209 below.
210 set_muted
212 $logger->set_muted($bool);
213 This sets the logger's muted property, which affects the behavior of
215 "log".
216 get_muted
218 This gets the logger's muted property, which affects the behavior of
219 "log".
220 clear_muted
222 This method does nothing, and is only useful for
223 Log::Dispatchouli::Proxy objects. See Methods for Proxy Loggers,
224 below.
225 get_prefix
227 my $prefix = $logger->get_prefix;
228 This method returns the currently-set prefix for the logger, which may
230 be a string or code reference or undef. See Logger Prefix.
231 set_prefix
233 $logger->set_prefix( $new_prefix );
234 This method changes the prefix. See Logger Prefix.
236 clear_prefix
238 This method clears any set logger prefix. (It can also be called as
239 "unset_prefix", but this is deprecated. See Logger Prefix.
240 ident
242 This method returns the logger's ident.
243 config_id
245 This method returns the logger's configuration id, which defaults to
246 its ident. This can be used to make two loggers equivalent in
247 Log::Dispatchouli::Global so that trying to reinitialize with a new
248 logger with the same "config_id" as the current logger will not throw
249 an exception, and will simply do no thing.
250 dispatcher
252 This returns the underlying Log::Dispatch object. This is not the
253 method you're looking for. Move along.
254 stdio_dispatcher_class
256 This method is an experimental feature to allow you to pick an
257 alternate dispatch class for stderr and stdio. By default,
258 Log::Dispatch::Screen is used. This feature may go away at any time.
259
261 Log messages may be prepended with information to set context. This
262 can be set at a logger level or per log item. The simplest example is:
263 my $logger = Log::Dispatchouli->new( ... );
265 $logger->set_prefix("Batch 123: ");
267 $logger->log("begun processing");
269 # ...
271 $logger->log("finished processing");
273 The above will log something like:
275 Batch 123: begun processing
277 Batch 123: finished processing
278 To pass a prefix per-message:
280 $logger->log({ prefix => 'Sub-Item 234: ' }, 'error!')
282 # Logs: Batch 123: Sub-Item 234: error!
284 If the prefix is a string, it is prepended to each line of the message.
286 If it is a coderef, it is called and passed the message to be logged.
287 The return value is logged instead.
288 Proxy loggers also have their own prefix settings, which accumulate.
290 So:
291 my $proxy = $logger->proxy({ proxy_prefix => 'Subsystem 12: ' });
293 $proxy->set_prefix('Page 9: ');
295 $proxy->log({ prefix => 'Paragraph 6: ' }, 'Done.');
297 ...will log...
299 Batch 123: Subsystem 12: Page 9: Paragraph 6: Done.
301
303 string_flogger
304 This method returns the thing on which flog will be called to format
305 log messages. By default, it just returns "String::Flogger"
306 env_prefix
308 This method should return a string used as a prefix to find environment
309 variables that affect the logger's behavior. For example, if this
310 method returns "XYZZY" then when checking the environment for a default
311 value for the "debug" parameter, Log::Dispatchouli will first check
312 "XYZZY_DEBUG", then "DISPATCHOULI_DEBUG".
313 By default, this method returns "()", which means no extra environment
315 variable is checked.
316 env_value
318 my $value = $logger->env_value('DEBUG');
319 This method returns the value for the environment variable suffix
321 given. For example, the example given, calling with "DEBUG" will check
322 "DISPATCHOULI_DEBUG".
323
325 new_tester
326 my $logger = Log::Dispatchouli->new_tester( \%arg );
327 This returns a new logger that logs only "to_self". It's useful in
329 testing. If no "ident" arg is provided, one will be generated.
330 "log_pid" is off by default, but can be overridden.
331 "\%arg" is optional.
333 events
335 This method returns the arrayref of events logged to an array in memory
336 (in the logger). If the logger is not logging "to_self" this raises an
337 exception.
338 clear_events
340 This method empties the current sequence of events logged into an array
341 in memory. If the logger is not logging "to_self" this raises an
342 exception.
343
345 proxy
346 my $proxy_logger = $logger->proxy( \%arg );
347 This method returns a new proxy logger -- an instance of
349 Log::Dispatchouli::Proxy -- which will log through the given logger,
350 but which may have some settings localized.
351 %arg is optional. It may contain the following entries:
353 proxy_prefix
355 This is a prefix that will be applied to anything the proxy logger
356 logs, and cannot be changed.
357 proxy_ctx
359 This is data to be inserted in front of event data logged through
360 the proxy. It will appear after the "event" key but before the
361 logged event data. It can be in the same format as the $data_ref
362 argument to "log_event".
363 debug
365 This can be set to true or false to change the proxy's "am I in
366 debug mode?" setting. It can be changed or cleared later on the
367 proxy.
368 parent
370 logger
371 These methods return the logger itself. (They're more useful when
372 called on proxy loggers.)
373
375 To provide compatibility with some other loggers, most specifically
376 Log::Contextual, the following methods are provided. You should not
377 use these methods without a good reason, and you should never subclass
378 them. Instead, subclass the methods they call.
379 is_debug
381 This method calls "get_debug".
382 is_info
384 is_fatal
385 These methods return true.
386 info
388 fatal
389 debug
390 These methods redispatch to "log", "log_fatal", and "log_debug"
391 respectively.
392
394 • Log::Dispatch
395 • String::Flogger
397
399 Ricardo SIGNES <cpan@semiotic.systems>
400
402 • Christopher J. Madsen <perl@cjmweb.net>
403 • Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
405 • Dan Book <grinnz@gmail.com>
407 • George Hartzell <hartzell@alerce.com>
409 • Jon Stuart <jon@fastmailteam.com>
411 • Matt Phillips <mattp@cpan.org>
413 • Olivier Mengué <dolmen@cpan.org>
415 • Randy Stauner <randy@magnificent-tears.com>
417 • Ricardo Signes <rjbs@semiotic.systems>
419 • Ricardo Signes <rjbs@users.noreply.github.com>
421 • Sawyer X <xsawyerx@cpan.org>
423
425 This software is copyright (c) 2023 by Ricardo SIGNES.
426 This is free software; you can redistribute it and/or modify it under
428 the same terms as the Perl 5 programming language system itself.
429perl v5.38.0 2023-08-23 Log::Dispatchouli(3)