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.017
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

LOGGER PREFIX

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

METHODS FOR SUBCLASSING

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

METHODS FOR TESTING

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

METHODS FOR PROXY LOGGERS

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

METHODS FOR API COMPATIBILITY

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

SEE ALSO

298       ·   Log::Dispatch
299
300       ·   String::Flogger
301

AUTHOR

303       Ricardo SIGNES <rjbs@cpan.org>
304

CONTRIBUTORS

306       ·   Christopher J. Madsen <perl@cjmweb.net>
307
308       ·   Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
309
310       ·   Dan Book <grinnz@gmail.com>
311
312       ·   George Hartzell <hartzell@alerce.com>
313
314       ·   Jon Stuart <jon@fastmailteam.com>
315
316       ·   Matt Phillips <mattp@cpan.org>
317
318       ·   Olivier Mengué <dolmen@cpan.org>
319
320       ·   Randy Stauner <randy@magnificent-tears.com>
321
322       ·   Sawyer X <xsawyerx@cpan.org>
323
325       This software is copyright (c) 2019 by Ricardo SIGNES.
326
327       This is free software; you can redistribute it and/or modify it under
328       the same terms as the Perl 5 programming language system itself.
329
330
331
332perl v5.28.1                      2019-03-13              Log::Dispatchouli(3)
Impressum