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

METHODS

44   new
45         my $logger = Log::Dispatchouli->new(\%arg);
46
47       This returns a new logger, a Log::Dispatchouli object.
48
49       Valid arguments are:
50
51         ident       - the name of the thing logging (mandatory)
52         to_self     - log to the logger object for testing; default: false
53         to_stdout   - log to STDOUT; default: false
54         to_stderr   - log to STDERR; default: false
55         facility    - to which syslog facility to send logs; default: none
56
57         to_file     - log to PROGRAM_NAME.YYYYMMDD in the log path; default: false
58         log_file    - a leaf name for the file to log to with to_file
59         log_path    - path in which to log to file; defaults to DISPATCHOULI_PATH
60                       environment variable or, failing that, to your system's tmpdir
61
62         file_format - this optional coderef is passed the message to be logged
63                       and returns the text to write out
64
65         log_pid     - if true, prefix all log entries with the pid; default: true
66         fail_fatal  - a boolean; if true, failure to log is fatal; default: true
67         muted       - a boolean; if true, only fatals are logged; default: false
68         debug       - a boolean; if true, log_debug method is not a no-op
69                       defaults to the truth of the DISPATCHOULI_DEBUG env var
70         quiet_fatal - 'stderr' or 'stdout' or an arrayref of zero, one, or both
71                       fatal log messages will not be logged to these
72                       (default: stderr)
73         config_id   - a name for this logger's config; rarely needed!
74         syslog_socket - a value for Sys::Syslog's "socket" arg; default: "native"
75
76       The log path is either /tmp or the value of the DISPATCHOULI_PATH env
77       var.
78
79       If the DISPATCHOULI_NOSYSLOG env var is true, we don't log to syslog.
80
81   log
82         $logger->log(@messages);
83
84         $logger->log(\%arg, @messages);
85
86       This method uses String::Flogger on the input, then unconditionally
87       logs the result.  Each message is flogged individually, then joined
88       with spaces.
89
90       If the first argument is a hashref, it will be used as extra arguments
91       to logging.  It may include a "prefix" entry to preprocess the message
92       by prepending a string (if the prefix is a string) or calling a
93       subroutine to generate a new message (if the prefix is a coderef).
94
95   log_fatal
96       This behaves like the "log" method, but will throw the logged string as
97       an exception after logging.
98
99       This method can also be called as "fatal", to match other popular
100       logging interfaces.  If you want to override this method, you must
101       override "log_fatal" and not "fatal".
102
103   log_debug
104       This behaves like the "log" method, but will only log (at the debug
105       level) if the logger object has its debug property set to true.
106
107       This method can also be called as "debug", to match other popular
108       logging interfaces.  If you want to override this method, you must
109       override "log_debug" and not "debug".
110
111   set_debug
112         $logger->set_debug($bool);
113
114       This sets the logger's debug property, which affects the behavior of
115       "log_debug".
116
117   get_debug
118       This gets the logger's debug property, which affects the behavior of
119       "log_debug".
120
121   clear_debug
122       This method does nothing, and is only useful for
123       Log::Dispatchouli::Proxy objects.  See Methods for Proxy Loggers,
124       below.
125
126   set_muted
127         $logger->set_muted($bool);
128
129       This sets the logger's muted property, which affects the behavior of
130       "log".
131
132   get_muted
133       This gets the logger's muted property, which affects the behavior of
134       "log".
135
136   clear_muted
137       This method does nothing, and is only useful for
138       Log::Dispatchouli::Proxy objects.  See Methods for Proxy Loggers,
139       below.
140
141   get_prefix
142         my $prefix = $logger->get_prefix;
143
144       This method returns the currently-set prefix for the logger, which may
145       be a string or code reference or undef.  See Logger Prefix.
146
147   set_prefix
148         $logger->set_prefix( $new_prefix );
149
150       This method changes the prefix.  See Logger Prefix.
151
152   clear_prefix
153       This method clears any set logger prefix.  (It can also be called as
154       "unset_prefix", but this is deprecated.  See Logger Prefix.
155
156   ident
157       This method returns the logger's ident.
158
159   config_id
160       This method returns the logger's configuration id, which defaults to
161       its ident.  This can be used to make two loggers equivalent in
162       Log::Dispatchouli::Global so that trying to reinitialize with a new
163       logger with the same "config_id" as the current logger will not throw
164       an exception, and will simply do no thing.
165
166   dispatcher
167       This returns the underlying Log::Dispatch object.  This is not the
168       method you're looking for.  Move along.
169
170   stdio_dispatcher_class
171       This method is an experimental feature to allow you to pick an
172       alternate dispatch class for stderr and stdio.  By default,
173       Log::Dispatch::Screen is used.  This feature may go away at any time.
174

LOGGER PREFIX

176       Log messages may be prepended with information to set context.  This
177       can be set at a logger level or per log item.  The simplest example is:
178
179         my $logger = Log::Dispatchouli->new( ... );
180
181         $logger->set_prefix("Batch 123: ");
182
183         $logger->log("begun processing");
184
185         # ...
186
187         $logger->log("finished processing");
188
189       The above will log something like:
190
191         Batch 123: begun processing
192         Batch 123: finished processing
193
194       To pass a prefix per-message:
195
196         $logger->log({ prefix => 'Sub-Item 234: ' }, 'error!')
197
198         # Logs: Batch 123: Sub-Item 234: error!
199
200       If the prefix is a string, it is prepended to each line of the message.
201       If it is a coderef, it is called and passed the message to be logged.
202       The return value is logged instead.
203
204       Proxy loggers also have their own prefix settings, which accumulate.
205       So:
206
207         my $proxy = $logger->proxy({ proxy_prefix => 'Subsystem 12: ' });
208
209         $proxy->set_prefix('Page 9: ');
210
211         $proxy->log({ prefix => 'Paragraph 6: ' }, 'Done.');
212
213       ...will log...
214
215         Batch 123: Subsystem 12: Page 9: Paragraph 6: Done.
216

METHODS FOR SUBCLASSING

218   string_flogger
219       This method returns the thing on which flog will be called to format
220       log messages.  By default, it just returns "String::Flogger"
221
222   env_prefix
223       This method should return a string used as a prefix to find environment
224       variables that affect the logger's behavior.  For example, if this
225       method returns "XYZZY" then when checking the environment for a default
226       value for the "debug" parameter, Log::Dispatchouli will first check
227       "XYZZY_DEBUG", then "DISPATCHOULI_DEBUG".
228
229       By default, this method returns "()", which means no extra environment
230       variable is checked.
231
232   env_value
233         my $value = $logger->env_value('DEBUG');
234
235       This method returns the value for the environment variable suffix
236       given.  For example, the example given, calling with "DEBUG" will check
237       "DISPATCHOULI_DEBUG".
238

METHODS FOR TESTING

240   new_tester
241         my $logger = Log::Dispatchouli->new_tester( \%arg );
242
243       This returns a new logger that logs only "to_self".  It's useful in
244       testing.  If no "ident" arg is provided, one will be generated.
245       "log_pid" is off by default, but can be overridden.
246
247       "\%arg" is optional.
248
249   events
250       This method returns the arrayref of events logged to an array in memory
251       (in the logger).  If the logger is not logging "to_self" this raises an
252       exception.
253
254   clear_events
255       This method empties the current sequence of events logged into an array
256       in memory.  If the logger is not logging "to_self" this raises an
257       exception.
258

METHODS FOR PROXY LOGGERS

260   proxy
261         my $proxy_logger = $logger->proxy( \%arg );
262
263       This method returns a new proxy logger -- an instance of
264       Log::Dispatchouli::Proxy -- which will log through the given logger,
265       but which may have some settings localized.
266
267       %arg is optional.  It may contain the following entries:
268
269       proxy_prefix
270           This is a prefix that will be applied to anything the proxy logger
271           logs, and cannot be changed.
272
273       debug
274           This can be set to true or false to change the proxy's "am I in
275           debug mode?"  setting.  It can be changed or cleared later on the
276           proxy.
277
278   parent
279   logger
280       These methods return the logger itself.  (They're more useful when
281       called on proxy loggers.)
282

METHODS FOR API COMPATIBILITY

284       To provide compatibility with some other loggers, most specifically
285       Log::Contextual, the following methods are provided.  You should not
286       use these methods without a good reason, and you should never subclass
287       them.  Instead, subclass the methods they call.
288
289       is_debug
290           This method calls "get_debug".
291
292       is_info
293       is_fatal
294           These methods return true.
295
296       info
297       fatal
298       debug
299           These methods redispatch to "log", "log_fatal", and "log_debug"
300           respectively.
301

SEE ALSO

303       •   Log::Dispatch
304
305       •   String::Flogger
306

AUTHOR

308       Ricardo SIGNES <rjbs@cpan.org>
309

CONTRIBUTORS

311       •   Christopher J. Madsen <perl@cjmweb.net>
312
313       •   Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
314
315       •   Dan Book <grinnz@gmail.com>
316
317       •   George Hartzell <hartzell@alerce.com>
318
319       •   Jon Stuart <jon@fastmailteam.com>
320
321       •   Matt Phillips <mattp@cpan.org>
322
323       •   Olivier Mengué <dolmen@cpan.org>
324
325       •   Randy Stauner <randy@magnificent-tears.com>
326
327       •   Ricardo Signes <rjbs@semiotic.systems>
328
329       •   Ricardo Signes <rjbs@users.noreply.github.com>
330
331       •   Sawyer X <xsawyerx@cpan.org>
332
334       This software is copyright (c) 2020 by Ricardo SIGNES.
335
336       This is free software; you can redistribute it and/or modify it under
337       the same terms as the Perl 5 programming language system itself.
338
339
340
341perl v5.32.1                      2021-01-27              Log::Dispatchouli(3)
Impressum