Log::Dispatch(3pm)

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

CONSTRUCTOR

63       The constructor ("new") takes the following parameters:
64
65       ·   outputs( [ [ class, params, ... ], [ class, params, ... ], ... ] )
66
67           This parameter is a reference to a list of lists. Each inner list
68           consists of a class name and a set of constructor params. The class
69           is automatically prefixed with 'Log::Dispatch::' unless it begins
70           with '+', in which case the string following '+' is taken to be a
71           full classname. e.g.
72
73               outputs => [ [ 'File',          min_level => 'debug', filename => 'logfile' ],
74                            [ '+My::Dispatch', min_level => 'info' ] ]
75
76           For each inner list, a new output object is created and added to
77           the dispatcher (via "add").
78
79           See "OUTPUT CLASSES" for the parameters that can be used when
80           creating an output object.
81
82       ·   callbacks( \& or [ \&, \&, ... ] )
83
84           This parameter may be a single subroutine reference or an array
85           reference of subroutine references.  These callbacks will be called
86           in the order they are given and passed a hash containing the
87           following keys:
88
89            ( message => $log_message, level => $log_level )
90
91           In addition, any key/value pairs passed to a logging method will be
92           passed onto your callback.
93
94           The callbacks are expected to modify the message and then return a
95           single scalar containing that modified message.  These callbacks
96           will be called when either the "log" or "log_to" methods are called
97           and will only be applied to a given message once.  If they do not
98           return the message then you will get no output.  Make sure to
99           return the message!
100

METHODS

102   Logging
103       ·   log( level => $, message => $ or \& )
104
105           Sends the message (at the appropriate level) to all the output
106           objects that the dispatcher contains (by calling the "log_to"
107           method repeatedly).
108
109           This method also accepts a subroutine reference as the message
110           argument. This reference will be called only if there is an output
111           that will accept a message of the specified level.
112
113       ·   debug (message), info (message), ...
114
115           You may call any valid log level (including valid abbreviations) as
116           a method with a single argument that is the message to be logged.
117           This is converted into a call to the "log" method with the
118           appropriate level.
119
120           For example:
121
122            $log->alert('Strange data in incoming request');
123
124           translates to:
125
126            $log->log( level => 'alert', message => 'Strange data in incoming request' );
127
128           If you pass an array to these methods, it will be stringified as
129           is:
130
131            my @array = ('Something', 'bad', 'is', here');
132            $log->alert(@array);
133
134            # is equivalent to
135
136            $log->alert("@array");
137
138       ·   log_and_die( level => $, message => $ or \& )
139
140           Has the same behavior as calling "log()" but calls
141           "_die_with_message()" at the end.
142
143       ·   log_and_croak( level => $, message => $ or \& )
144
145           This method adjusts the $Carp::CarpLevel scalar so that the croak
146           comes from the context in which it is called.
147
148       ·   _die_with_message( message => $, carp_level => $ )
149
150           This method is used by "log_and_die" and will either die() or
151           croak() depending on the value of "message": if it's a reference or
152           it ends with a new line then a plain die will be used, otherwise it
153           will croak.
154
155           You can throw exception objects by subclassing this method.
156
157           If the "carp_level" parameter is present its value will be added to
158           the current value of $Carp::CarpLevel.
159
160       ·   log_to( name => $, level => $, message => $ )
161
162           Sends the message only to the named object. Note: this will not
163           properly handle a subroutine reference as the message.
164
165       ·   add_callback( $code )
166
167           Adds a callback (like those given during construction). It is added
168           to the end of the list of callbacks. Note that this can also be
169           called on individual output objects.
170
171   Log levels
172       ·   level_is_valid( $string )
173
174           Returns true or false to indicate whether or not the given string
175           is a valid log level.  Can be called as either a class or object
176           method.
177
178       ·   would_log( $string )
179
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   Output objects
184       ·   add( Log::Dispatch::* OBJECT )
185
186           Adds a new output object to the dispatcher.  If an object of the
187           same name already exists, then that object is replaced, with a
188           warning if $^W is true.
189
190       ·   remove($)
191
192           Removes the object that matches the name given to the remove
193           method.  The return value is the object being removed or undef if
194           no object matched this.
195
196       ·   output( $name )
197
198           Returns the output object of the given name.  Returns undef or an
199           empty list, depending on context, if the given output does not
200           exist.
201

OUTPUT CLASSES

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

LOG LEVELS

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

SUBCLASSING

273       This module was designed to be easy to subclass. If you want to handle
274       messaging in a way not implemented in this package, you should be able
275       to add this with minimal effort. It is generally as simple as
276       subclassing Log::Dispatch::Output and overriding the "new" and
277       "log_message" methods. See the Log::Dispatch::Output docs for more
278       details.
279
280       If you would like to create your own subclass for sending email then it
281       is even simpler.  Simply subclass Log::Dispatch::Email and override the
282       "send_email" method.  See the Log::Dispatch::Email docs for more
283       details.
284
285       The logging levels that Log::Dispatch uses are borrowed from the
286       standard UNIX syslog levels, except that where syslog uses partial
287       words ("err") Log::Dispatch also allows the use of the full word as
288       well ("error").
289

RELATED MODULES

291   Log::Dispatch::DBI
292       Written by Tatsuhiko Miyagawa.  Log output to a database table.
293
294   Log::Dispatch::FileRotate
295       Written by Mark Pfeiffer.  Rotates log files periodically as part of
296       its usage.
297
298   Log::Dispatch::File::Stamped
299       Written by Eric Cholet.  Stamps log files with date and time
300       information.
301
302   Log::Dispatch::Jabber
303       Written by Aaron Straup Cope.  Logs messages via Jabber.
304
305   Log::Dispatch::Tk
306       Written by Dominique Dumont.  Logs messages to a Tk window.
307
308   Log::Dispatch::Win32EventLog
309       Written by Arthur Bergman.  Logs messages to the Windows event log.
310
311   Log::Log4perl
312       An implementation of Java's log4j API in Perl. Log messages can be
313       limited by fine-grained controls, and if they end up being logged, both
314       native Log4perl and Log::Dispatch appenders can be used to perform the
315       actual logging job. Created by Mike Schilli and Kevin Goess.
316
317   Log::Dispatch::Config
318       Written by Tatsuhiko Miyagawa.  Allows configuration of logging via a
319       text file similar (or so I'm told) to how it is done with log4j.
320       Simpler than Log::Log4perl.
321
322   Log::Agent
323       A very different API for doing many of the same things that
324       Log::Dispatch does.  Originally written by Raphael Manfredi.
325

SUPPORT

327       Please submit bugs and patches to the CPAN RT system at
328       http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Log%3A%3ADispatch or via
329       email at bug-log-dispatch@rt.cpan.org.
330
331       Support questions can be sent to me at my email address, shown below.
332
333       The code repository is at http://hg.urth.org/hg/Log-Dispatch.
334

AUTHOR

344       Dave Rolsky <autarch@urth.org>
345

COPYRIGHT AND LICENSE

347       This software is Copyright (c) 2010 by Dave Rolsky.
348
349       This is free software, licensed under:
350
351         The Artistic License 2.0
352
353
354
355perl v5.12.2                      2010-10-16                  Log::Dispatch(3)