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

NAME

6       Log::Dispatch - Dispatches messages to one or more outputs
7

VERSION

9       version 2.70
10

SYNOPSIS

12         use Log::Dispatch;
13
14         # Simple API
15         #
16         my $log = Log::Dispatch->new(
17             outputs => [
18                 [ 'File',   min_level => 'debug', filename => 'logfile' ],
19                 [ 'Screen', min_level => 'warning' ],
20             ],
21         );
22
23         $log->info('Blah, blah');
24
25         # More verbose API
26         #
27         my $log = Log::Dispatch->new();
28         $log->add(
29             Log::Dispatch::File->new(
30                 name      => 'file1',
31                 min_level => 'debug',
32                 filename  => 'logfile'
33             )
34         );
35         $log->add(
36             Log::Dispatch::Screen->new(
37                 name      => 'screen',
38                 min_level => 'warning',
39             )
40         );
41
42         $log->log( level => 'info', message => 'Blah, blah' );
43
44         my $sub = sub { my %p = @_; return reverse $p{message}; };
45         my $reversing_dispatcher = Log::Dispatch->new( callbacks => $sub );
46

DESCRIPTION

48       This module manages a set of Log::Dispatch::* output objects that can
49       be logged to via a unified interface.
50
51       The idea is that you create a Log::Dispatch object and then add various
52       logging objects to it (such as a file logger or screen logger). Then
53       you call the "log" method of the dispatch object, which passes the
54       message to each of the objects, which in turn decide whether or not to
55       accept the message and what to do with it.
56
57       This makes it possible to call single method and send a message to a
58       log file, via email, to the screen, and anywhere else, all with very
59       little code needed on your part, once the dispatching object has been
60       created.
61

METHODS

63       This class provides the following methods:
64
65   Log::Dispatch->new(...)
66       This method takes the following parameters:
67
68       ·   outputs( [ [ class, params, ... ], [ class, params, ... ], ... ] )
69
70           This parameter is a reference to a list of lists. Each inner list
71           consists of a class name and a set of constructor params. The class
72           is automatically prefixed with 'Log::Dispatch::' unless it begins
73           with '+', in which case the string following '+' is taken to be a
74           full classname. e.g.
75
76               outputs => [ [ 'File',          min_level => 'debug', filename => 'logfile' ],
77                            [ '+My::Dispatch', min_level => 'info' ] ]
78
79           For each inner list, a new output object is created and added to
80           the dispatcher (via the "add()" method).
81
82           See "OUTPUT CLASSES" for the parameters that can be used when
83           creating an output object.
84
85       ·   callbacks( \& or [ \&, \&, ... ] )
86
87           This parameter may be a single subroutine reference or an array
88           reference of subroutine references. These callbacks will be called
89           in the order they are given and passed a hash containing the
90           following keys:
91
92            ( message => $log_message, level => $log_level )
93
94           In addition, any key/value pairs passed to a logging method will be
95           passed onto your callback.
96
97           The callbacks are expected to modify the message and then return a
98           single scalar containing that modified message. These callbacks
99           will be called when either the "log" or "log_to" methods are called
100           and will only be applied to a given message once. If they do not
101           return the message then you will get no output. Make sure to return
102           the message!
103
104   $dispatch->clone()
105       This returns a shallow clone of the original object. The underlying
106       output objects and callbacks are shared between the two objects.
107       However any changes made to the outputs or callbacks that the object
108       contains are not shared.
109
110   $dispatch->log( level => $, message => $ or \& )
111       Sends the message (at the appropriate level) to all the output objects
112       that the dispatcher contains (by calling the "log_to" method
113       repeatedly).
114
115       The level can be specified by name or by an integer from 0 (debug) to 7
116       (emergency).
117
118       This method also accepts a subroutine reference as the message
119       argument. This reference will be called only if there is an output that
120       will accept a message of the specified level.
121
122   $dispatch->debug (message), info (message), ...
123       You may call any valid log level (including valid abbreviations) as a
124       method with a single argument that is the message to be logged. This is
125       converted into a call to the "log" method with the appropriate level.
126
127       For example:
128
129        $log->alert('Strange data in incoming request');
130
131       translates to:
132
133        $log->log( level => 'alert', message => 'Strange data in incoming request' );
134
135       If you pass an array to these methods, it will be stringified as is:
136
137        my @array = ('Something', 'bad', 'is', 'here');
138        $log->alert(@array);
139
140        # is equivalent to
141
142        $log->alert("@array");
143
144       You can also pass a subroutine reference, just like passing one to the
145       "log()" method.
146
147   $dispatch->log_and_die( level => $, message => $ or \& )
148       Has the same behavior as calling "log()" but calls
149       "_die_with_message()" at the end.
150
151       You can throw exception objects by subclassing this method.
152
153       If the "carp_level" parameter is present its value will be added to the
154       current value of $Carp::CarpLevel.
155
156   $dispatch->log_and_croak( level => $, message => $ or \& )
157       A synonym for "$dispatch-"log_and_die()>.
158
159   $dispatch->log_to( name => $, level => $, message => $ )
160       Sends the message only to the named object. Note: this will not
161       properly handle a subroutine reference as the message.
162
163   $dispatch->add_callback( $code )
164       Adds a callback (like those given during construction). It is added to
165       the end of the list of callbacks. Note that this can also be called on
166       individual output objects.
167
168   $dispatch->remove_callback( $code )
169       Remove the given callback from the list of callbacks. Note that this
170       can also be called on individual output objects.
171
172   $dispatch->callbacks()
173       Returns a list of the callbacks in a given output.
174
175   $dispatch->level_is_valid( $string )
176       Returns true or false to indicate whether or not the given string is a
177       valid log level. Can be called as either a class or object method.
178
179   $dispatch->would_log( $string )
180       Given a log level, returns true or false to indicate whether or not
181       anything would be logged for that log level.
182
183   $dispatch->is_$level
184       There are methods for every log level: "is_debug()", "is_warning()",
185       etc.
186
187       This returns true if the logger will log a message at the given level.
188
189   $dispatch->add( Log::Dispatch::* OBJECT )
190       Adds a new output object to the dispatcher. If an object of the same
191       name already exists, then that object is replaced, with a warning if
192       $^W is true.
193
194   $dispatch->remove($)
195       Removes the output object that matches the name given to the remove
196       method.  The return value is the object being removed or undef if no
197       object matched this.
198
199   $dispatch->outputs()
200       Returns a list of output objects.
201
202   $dispatch->output( $name )
203       Returns the output object of the given name. Returns undef or an empty
204       list, depending on context, if the given output does not exist.
205
206   $dispatch->_die_with_message( message => $, carp_level => $ )
207       This method is used by "log_and_die" and will either die() or croak()
208       depending on the value of "message": if it's a reference or it ends
209       with a new line then a plain die will be used, otherwise it will croak.
210

OUTPUT CLASSES

212       An output class - e.g. Log::Dispatch::File or Log::Dispatch::Screen -
213       implements a particular way of dispatching logs. Many output classes
214       come with this distribution, and others are available separately on
215       CPAN.
216
217       The following common parameters can be used when creating an output
218       class.  All are optional. Most output classes will have additional
219       parameters beyond these, see their documentation for details.
220
221       ·   name ($)
222
223           A name for the object (not the filename!). This is useful if you
224           want to refer to the object later, e.g. to log specifically to it
225           or remove it.
226
227           By default a unique name will be generated. You should not depend
228           on the form of generated names, as they may change.
229
230       ·   min_level ($)
231
232           The minimum logging level this object will accept. Required.
233
234       ·   max_level ($)
235
236           The maximum logging level this object will accept. By default the
237           maximum is the highest possible level (which means functionally
238           that the object has no maximum).
239
240       ·   callbacks( \& or [ \&, \&, ... ] )
241
242           This parameter may be a single subroutine reference or an array
243           reference of subroutine references. These callbacks will be called
244           in the order they are given and passed a hash containing the
245           following keys:
246
247            ( message => $log_message, level => $log_level )
248
249           The callbacks are expected to modify the message and then return a
250           single scalar containing that modified message. These callbacks
251           will be called when either the "log" or "log_to" methods are called
252           and will only be applied to a given message once. If they do not
253           return the message then you will get no output. Make sure to return
254           the message!
255
256       ·   newline (0|1)
257
258           If true, a callback will be added to the end of the callbacks list
259           that adds a newline to the end of each message. Default is false,
260           but some output classes may decide to make the default true.
261

LOG LEVELS

263       The log levels that Log::Dispatch uses are taken directly from the
264       syslog man pages (except that I expanded them to full words). Valid
265       levels are:
266
267       debug
268       info
269       notice
270       warning
271       error
272       critical
273       alert
274       emergency
275
276       Alternately, the numbers 0 through 7 may be used (debug is 0 and
277       emergency is 7). The syslog standard of 'err', 'crit', and 'emerg' is
278       also acceptable. We also allow 'warn' as a synonym for 'warning'.
279

SUBCLASSING

281       This module was designed to be easy to subclass. If you want to handle
282       messaging in a way not implemented in this package, you should be able
283       to add this with minimal effort. It is generally as simple as
284       subclassing Log::Dispatch::Output and overriding the "new" and
285       "log_message" methods. See the Log::Dispatch::Output docs for more
286       details.
287
288       If you would like to create your own subclass for sending email then it
289       is even simpler. Simply subclass Log::Dispatch::Email and override the
290       "send_email" method. See the Log::Dispatch::Email docs for more
291       details.
292
293       The logging levels that Log::Dispatch uses are borrowed from the
294       standard UNIX syslog levels, except that where syslog uses partial
295       words ("err") Log::Dispatch also allows the use of the full word as
296       well ("error").
297
299   Log::Dispatch::DBI
300       Written by Tatsuhiko Miyagawa. Log output to a database table.
301
302   Log::Dispatch::FileRotate
303       Written by Mark Pfeiffer. Rotates log files periodically as part of its
304       usage.
305
306   Log::Dispatch::File::Stamped
307       Written by Eric Cholet. Stamps log files with date and time
308       information.
309
310   Log::Dispatch::Jabber
311       Written by Aaron Straup Cope. Logs messages via Jabber.
312
313   Log::Dispatch::Tk
314       Written by Dominique Dumont. Logs messages to a Tk window.
315
316   Log::Dispatch::Win32EventLog
317       Written by Arthur Bergman. Logs messages to the Windows event log.
318
319   Log::Log4perl
320       An implementation of Java's log4j API in Perl. Log messages can be
321       limited by fine-grained controls, and if they end up being logged, both
322       native Log4perl and Log::Dispatch appenders can be used to perform the
323       actual logging job. Created by Mike Schilli and Kevin Goess.
324
325   Log::Dispatch::Config
326       Written by Tatsuhiko Miyagawa. Allows configuration of logging via a
327       text file similar (or so I'm told) to how it is done with log4j.
328       Simpler than Log::Log4perl.
329
330   Log::Agent
331       A very different API for doing many of the same things that
332       Log::Dispatch does. Originally written by Raphael Manfredi.
333

SEE ALSO

335       Log::Dispatch::ApacheLog, Log::Dispatch::Email,
336       Log::Dispatch::Email::MailSend, Log::Dispatch::Email::MailSender,
337       Log::Dispatch::Email::MailSendmail, Log::Dispatch::Email::MIMELite,
338       Log::Dispatch::File, Log::Dispatch::File::Locked,
339       Log::Dispatch::Handle, Log::Dispatch::Output, Log::Dispatch::Screen,
340       Log::Dispatch::Syslog
341

SUPPORT

343       Bugs may be submitted at
344       <https://github.com/houseabsolute/Log-Dispatch/issues>.
345
346       I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
347

SOURCE

349       The source code repository for Log-Dispatch can be found at
350       <https://github.com/houseabsolute/Log-Dispatch>.
351

DONATIONS

353       If you'd like to thank me for the work I've done on this module, please
354       consider making a "donation" to me via PayPal. I spend a lot of free
355       time creating free software, and would appreciate any support you'd
356       care to offer.
357
358       Please note that I am not suggesting that you must do this in order for
359       me to continue working on this particular software. I will continue to
360       do so, inasmuch as I have in the past, for as long as it interests me.
361
362       Similarly, a donation made in this way will probably not make me work
363       on this software much more, unless I get so many donations that I can
364       consider working on free software full time (let's all have a chuckle
365       at that together).
366
367       To donate, log into PayPal and send money to autarch@urth.org, or use
368       the button at <https://www.urth.org/fs-donation.html>.
369

AUTHOR

371       Dave Rolsky <autarch@urth.org>
372

CONTRIBUTORS

374       ·   Anirvan Chatterjee <anirvan@users.noreply.github.com>
375
376       ·   Carsten Grohmann <mail@carstengrohmann.de>
377
378       ·   Doug Bell <doug@preaction.me>
379
380       ·   Graham Knop <haarg@haarg.org>
381
382       ·   Graham Ollis <plicease@cpan.org>
383
384       ·   Gregory Oschwald <goschwald@maxmind.com>
385
386       ·   hartzell <hartzell@alerce.com>
387
388       ·   Joelle Maslak <jmaslak@antelope.net>
389
390       ·   Johann Rolschewski <jorol@cpan.org>
391
392       ·   Jonathan Swartz <swartz@pobox.com>
393
394       ·   Karen Etheridge <ether@cpan.org>
395
396       ·   Kerin Millar <kfm@plushkava.net>
397
398       ·   Kivanc Yazan <kivancyazan@gmail.com>
399
400       ·   Konrad Bucheli <kb@open.ch>
401
402       ·   Michael Schout <mschout@gkg.net>
403
404       ·   Olaf Alders <olaf@wundersolutions.com>
405
406       ·   Olivier Mengué <dolmen@cpan.org>
407
408       ·   Rohan Carly <se456@rohan.id.au>
409
410       ·   Ross Attrill <ross.attrill@gmail.com>
411
412       ·   Salvador Fandiño <sfandino@yahoo.com>
413
414       ·   Sergey Leschenko <sergle.ua@gmail.com>
415
416       ·   Slaven Rezic <srezic@cpan.org>
417
418       ·   Steve Bertrand <steveb@cpan.org>
419
420       ·   Whitney Jackson <whitney.jackson@baml.com>
421
423       This software is Copyright (c) 2020 by Dave Rolsky.
424
425       This is free software, licensed under:
426
427         The Artistic License 2.0 (GPL Compatible)
428
429       The full text of the license can be found in the LICENSE file included
430       with this distribution.
431
432
433
434perl v5.32.0                      2020-07-31                  Log::Dispatch(3)
Impressum