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

NAME

6       Log::Dispatchouli - a simple wrapper around Log::Dispatch
7

VERSION

9       version 3.006
10

SYNOPSIS

12         my $logger = Log::Dispatchouli->new({
13           ident     => 'stuff-purger',
14           facility  => 'daemon',
15           to_stdout => $opt->{print},
16           debug     => $opt->{verbose}
17         });
18
19         $logger->log([ "There are %s items left to purge...", $stuff_left ]);
20
21         $logger->log_debug("this is extra often-ignored debugging log");
22
23         $logger->log_fatal("Now we will die!!");
24

DESCRIPTION

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
32       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
36       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

PERL VERSION

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
47       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

METHODS

53   new
54         my $logger = Log::Dispatchouli->new(\%arg);
55
56       This returns a new logger, a Log::Dispatchouli object.
57
58       Valid arguments are:
59
60         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
66         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
71         file_format - this optional coderef is passed the message to be logged
72                       and returns the text to write out
73
74         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
85       The log path is either /tmp or the value of the DISPATCHOULI_PATH env
86       var.
87
88       If the DISPATCHOULI_NOSYSLOG env var is true, we don't log to syslog.
89
90   log
91         $logger->log(@messages);
92
93         $logger->log(\%arg, @messages);
94
95       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
99       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
104   log_fatal
105       This behaves like the "log" method, but will throw the logged string as
106       an exception after logging.
107
108       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
112   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
116       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
120   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
124         $logger->log($event_type => $data_ref);
125
126       $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
131       $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
135       The logged string will be in logfmt format, meaning a series of
136       key=value pairs separated by spaces and following these rules:
137
138       •   an "identifier" is a string of printable ASCII characters between
139           "!" and "~", excluding "\" and "="
140
141       •   keys must be valid identifiers
142
143       •   if a key is empty, "~" is used instead
144
145       •   if a key contains characters not permitted in an identifier, they
146           are replaced by "?"
147
148       •   values must either be valid identifiers, or be quoted
149
150       •   quoted value start and end with """
151
152       •   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
157       When values are undef, they are represented as "~".
158
159       When values are array references, the index/values are mapped over, so
160       that:
161
162         key => [ 'a', 'b' ]
163
164       becomes
165
166         key.0=a key.1=b
167
168       When values are hash references, the key/values are mapped, with keys
169       sorted, so that:
170
171         key => { b => 2, a => 1 }
172
173       becomes
174
175         key.a=1 key.b=2
176
177       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
183       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
187       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
192   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
196   set_debug
197         $logger->set_debug($bool);
198
199       This sets the logger's debug property, which affects the behavior of
200       "log_debug".
201
202   get_debug
203       This gets the logger's debug property, which affects the behavior of
204       "log_debug".
205
206   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
211   set_muted
212         $logger->set_muted($bool);
213
214       This sets the logger's muted property, which affects the behavior of
215       "log".
216
217   get_muted
218       This gets the logger's muted property, which affects the behavior of
219       "log".
220
221   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
226   get_prefix
227         my $prefix = $logger->get_prefix;
228
229       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
232   set_prefix
233         $logger->set_prefix( $new_prefix );
234
235       This method changes the prefix.  See Logger Prefix.
236
237   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
241   ident
242       This method returns the logger's ident.
243
244   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
251   dispatcher
252       This returns the underlying Log::Dispatch object.  This is not the
253       method you're looking for.  Move along.
254
255   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

LOGGER PREFIX

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
264         my $logger = Log::Dispatchouli->new( ... );
265
266         $logger->set_prefix("Batch 123: ");
267
268         $logger->log("begun processing");
269
270         # ...
271
272         $logger->log("finished processing");
273
274       The above will log something like:
275
276         Batch 123: begun processing
277         Batch 123: finished processing
278
279       To pass a prefix per-message:
280
281         $logger->log({ prefix => 'Sub-Item 234: ' }, 'error!')
282
283         # Logs: Batch 123: Sub-Item 234: error!
284
285       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
289       Proxy loggers also have their own prefix settings, which accumulate.
290       So:
291
292         my $proxy = $logger->proxy({ proxy_prefix => 'Subsystem 12: ' });
293
294         $proxy->set_prefix('Page 9: ');
295
296         $proxy->log({ prefix => 'Paragraph 6: ' }, 'Done.');
297
298       ...will log...
299
300         Batch 123: Subsystem 12: Page 9: Paragraph 6: Done.
301

METHODS FOR SUBCLASSING

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
307   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
314       By default, this method returns "()", which means no extra environment
315       variable is checked.
316
317   env_value
318         my $value = $logger->env_value('DEBUG');
319
320       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

METHODS FOR TESTING

325   new_tester
326         my $logger = Log::Dispatchouli->new_tester( \%arg );
327
328       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
332       "\%arg" is optional.
333
334   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
339   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

METHODS FOR PROXY LOGGERS

345   proxy
346         my $proxy_logger = $logger->proxy( \%arg );
347
348       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
352       %arg is optional.  It may contain the following entries:
353
354       proxy_prefix
355           This is a prefix that will be applied to anything the proxy logger
356           logs, and cannot be changed.
357
358       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
364       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
369   parent
370   logger
371       These methods return the logger itself.  (They're more useful when
372       called on proxy loggers.)
373

METHODS FOR API COMPATIBILITY

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
380       is_debug
381           This method calls "get_debug".
382
383       is_info
384       is_fatal
385           These methods return true.
386
387       info
388       fatal
389       debug
390           These methods redispatch to "log", "log_fatal", and "log_debug"
391           respectively.
392

SEE ALSO

394       •   Log::Dispatch
395
396       •   String::Flogger
397

AUTHOR

399       Ricardo SIGNES <cpan@semiotic.systems>
400

CONTRIBUTORS

402       •   Christopher J. Madsen <perl@cjmweb.net>
403
404       •   Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
405
406       •   Dan Book <grinnz@gmail.com>
407
408       •   George Hartzell <hartzell@alerce.com>
409
410       •   Jon Stuart <jon@fastmailteam.com>
411
412       •   Matt Phillips <mattp@cpan.org>
413
414       •   Olivier Mengué <dolmen@cpan.org>
415
416       •   Randy Stauner <randy@magnificent-tears.com>
417
418       •   Ricardo Signes <rjbs@semiotic.systems>
419
420       •   Ricardo Signes <rjbs@users.noreply.github.com>
421
422       •   Sawyer X <xsawyerx@cpan.org>
423
425       This software is copyright (c) 2023 by Ricardo SIGNES.
426
427       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.
429
430
431
432perl v5.38.0                      2023-08-23              Log::Dispatchouli(3)
Impressum