1Log::Dispatch(3) User Contributed Perl Documentation Log::Dispatch(3)
2
6 Log::Dispatch - Dispatches messages to one or more outputs
7
9 version 2.70
10
12 use Log::Dispatch;
13 # 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 $log->info('Blah, blah');
24 # 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 $log->log( level => 'info', message => 'Blah, blah' );
43 my $sub = sub { my %p = @_; return reverse $p{message}; };
45 my $reversing_dispatcher = Log::Dispatch->new( callbacks => $sub );
46
48 This module manages a set of Log::Dispatch::* output objects that can
49 be logged to via a unified interface.
50 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 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
63 This class provides the following methods:
64 Log::Dispatch->new(...)
66 This method takes the following parameters:
67 · outputs( [ [ class, params, ... ], [ class, params, ... ], ... ] )
69 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 outputs => [ [ 'File', min_level => 'debug', filename => 'logfile' ],
77 [ '+My::Dispatch', min_level => 'info' ] ]
78 For each inner list, a new output object is created and added to
80 the dispatcher (via the "add()" method).
81 See "OUTPUT CLASSES" for the parameters that can be used when
83 creating an output object.
84 · callbacks( \& or [ \&, \&, ... ] )
86 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 ( message => $log_message, level => $log_level )
93 In addition, any key/value pairs passed to a logging method will be
95 passed onto your callback.
96 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 $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 $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 The level can be specified by name or by an integer from 0 (debug) to 7
116 (emergency).
117 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 $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 For example:
128 $log->alert('Strange data in incoming request');
130 translates to:
132 $log->log( level => 'alert', message => 'Strange data in incoming request' );
134 If you pass an array to these methods, it will be stringified as is:
136 my @array = ('Something', 'bad', 'is', 'here');
138 $log->alert(@array);
139 # is equivalent to
141 $log->alert("@array");
143 You can also pass a subroutine reference, just like passing one to the
145 "log()" method.
146 $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 You can throw exception objects by subclassing this method.
152 If the "carp_level" parameter is present its value will be added to the
154 current value of $Carp::CarpLevel.
155 $dispatch->log_and_croak( level => $, message => $ or \& )
157 A synonym for "$dispatch-"log_and_die()>.
158 $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 $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 $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 $dispatch->callbacks()
173 Returns a list of the callbacks in a given output.
174 $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 $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 $dispatch->is_$level
184 There are methods for every log level: "is_debug()", "is_warning()",
185 etc.
186 This returns true if the logger will log a message at the given level.
188 $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 $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 $dispatch->outputs()
200 Returns a list of output objects.
201 $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 $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
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 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 · name ($)
222 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 By default a unique name will be generated. You should not depend
228 on the form of generated names, as they may change.
229 · min_level ($)
231 The minimum logging level this object will accept. Required.
233 · max_level ($)
235 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 · callbacks( \& or [ \&, \&, ... ] )
241 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 ( message => $log_message, level => $log_level )
248 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 · newline (0|1)
257 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
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 debug
268 info
269 notice
270 warning
271 error
272 critical
273 alert
274 emergency
275 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
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 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 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 Log::Dispatch::FileRotate
303 Written by Mark Pfeiffer. Rotates log files periodically as part of its
304 usage.
305 Log::Dispatch::File::Stamped
307 Written by Eric Cholet. Stamps log files with date and time
308 information.
309 Log::Dispatch::Jabber
311 Written by Aaron Straup Cope. Logs messages via Jabber.
312 Log::Dispatch::Tk
314 Written by Dominique Dumont. Logs messages to a Tk window.
315 Log::Dispatch::Win32EventLog
317 Written by Arthur Bergman. Logs messages to the Windows event log.
318 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 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 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
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
343 Bugs may be submitted at
344 <https://github.com/houseabsolute/Log-Dispatch/issues>.
345 I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
347
349 The source code repository for Log-Dispatch can be found at
350 <https://github.com/houseabsolute/Log-Dispatch>.
351
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 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 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 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
371 Dave Rolsky <autarch@urth.org>
372
374 · Anirvan Chatterjee <anirvan@users.noreply.github.com>
375 · Carsten Grohmann <mail@carstengrohmann.de>
377 · Doug Bell <doug@preaction.me>
379 · Graham Knop <haarg@haarg.org>
381 · Graham Ollis <plicease@cpan.org>
383 · Gregory Oschwald <goschwald@maxmind.com>
385 · hartzell <hartzell@alerce.com>
387 · Joelle Maslak <jmaslak@antelope.net>
389 · Johann Rolschewski <jorol@cpan.org>
391 · Jonathan Swartz <swartz@pobox.com>
393 · Karen Etheridge <ether@cpan.org>
395 · Kerin Millar <kfm@plushkava.net>
397 · Kivanc Yazan <kivancyazan@gmail.com>
399 · Konrad Bucheli <kb@open.ch>
401 · Michael Schout <mschout@gkg.net>
403 · Olaf Alders <olaf@wundersolutions.com>
405 · Olivier Mengué <dolmen@cpan.org>
407 · Rohan Carly <se456@rohan.id.au>
409 · Ross Attrill <ross.attrill@gmail.com>
411 · Salvador Fandiño <sfandino@yahoo.com>
413 · Sergey Leschenko <sergle.ua@gmail.com>
415 · Slaven Rezic <srezic@cpan.org>
417 · Steve Bertrand <steveb@cpan.org>
419 · Whitney Jackson <whitney.jackson@baml.com>
421
423 This software is Copyright (c) 2020 by Dave Rolsky.
424 This is free software, licensed under:
426 The Artistic License 2.0 (GPL Compatible)
428 The full text of the license can be found in the LICENSE file included
430 with this distribution.
431perl v5.32.0 2020-07-31 Log::Dispatch(3)