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

SYNOPSIS

9         use Log::Dispatch;
10
11         my $dispatcher = Log::Dispatch->new;
12
13         $dispatcher->add( Log::Dispatch::File->new( name => 'file1',
14                                                     min_level => 'debug',
15                                                     filename => 'logfile' ) );
16
17         $dispatcher->log( level => 'info',
18                           message => 'Blah, blah' );
19
20         my $sub = sub { my %p = @_;  return reverse $p{message}; };
21         my $reversing_dispatcher = Log::Dispatch->new( callbacks => $sub );
22

DESCRIPTION

24       This module manages a set of Log::Dispatch::* objects, allowing you to
25       add and remove output objects as desired.
26

METHODS

28       * new
29           Returns a new Log::Dispatch object.  This method takes one optional
30           parameter:
31
32           * callbacks( \& or [ \&, \&, ... ] )
33                   This parameter may be a single subroutine reference or an
34                   array reference of subroutine references.  These callbacks
35                   will be called in the order they are given and passed a
36                   hash containing the following keys:
37
38                    ( message => $log_message, level => $log_level )
39
40                   In addition, any key/value pairs passed to a logging method
41                   will be passed onto your callback.
42
43                   The callbacks are expected to modify the message and then
44                   return a single scalar containing that modified message.
45                   These callbacks will be called when either the "log" or
46                   "log_to" methods are called and will only be applied to a
47                   given message once.  If they do not return the message then
48                   you will get no output.  Make sure to return the message!
49
50       * add( Log::Dispatch::* OBJECT )
51           Adds a new a Log::Dispatch::* object to the dispatcher.  If an
52           object of the same name already exists, then that object is
53           replaced.  A warning will be issued if the $^W is true.
54
55           NOTE: This method can really take any object that has methods
56           called 'name' and 'log'.
57
58       * remove($)
59           Removes the object that matches the name given to the remove
60           method.  The return value is the object being removed or undef if
61           no object matched this.
62
63       * log( level => $, message => $ or \& )
64           Sends the message (at the appropriate level) to all the Log::Dis‐
65           patch::* objects that the dispatcher contains (by calling the
66           "log_to" method repeatedly).
67
68           This method also accepts a subroutine reference as the message
69           argument. This reference will be called only if there is an output
70           that will accept a message of the specified level.
71
72           WARNING: This is the only logging method that does something intel‐
73           ligent with a subroutine reference as the message. Other methods,
74           like "log_to()" or the "log()" method of an output object, will
75           just stringify the reference.
76
77       * log_to( name => $, level => $, message => $ )
78           Sends the message only to the named object.
79
80       * level_is_valid( $string )
81           Returns true or false to indicate whether or not the given string
82           is a valid log level.  Can be called as either a class or object
83           method.
84
85       * would_log( $string )
86           Given a log level, returns true or false to indicate whether or not
87           anything would be logged for that log level.
88
89       * output( $name )
90           Returns an output of the given name.  Returns undef or an empty
91           list, depending on context, if the given output does not exist.
92

CONVENIENCE METHODS

94       Version 1.6 of Log::Dispatch adds a number of convenience methods for
95       logging.  You may now call any valid log level (including valid abbre‐
96       viations) as a method on the Log::Dispatch object with a single argu‐
97       ment that is the message to be logged.  This is converted into a call
98       to the "log" method with the appropriate level.
99
100       For example:
101
102        $dispatcher->alert('Strange data in incoming request');
103
104       translates to:
105
106        $dispatcher->log( level => 'alert', message => 'Strange data in incoming request' );
107
108       These methods act like Perl's "print" built-in when given a list of
109       arguments.  Thus, the following calls are equivalent:
110
111        my @array = ('Something', 'bad', 'is', here');
112        $dispatcher->alert(@array);
113
114        my $scalar = "@array";
115        $dispatcher->alert($scalar);
116
117       One important caveat about these methods is that its not that forwards
118       compatible.  If I were to add more parameters to the "log" call, it is
119       unlikely that these could be integrated into these methods without
120       breaking existing uses.  This probably means that any future parameters
121       to the "log" method will never be integrated into these convenience
122       methods.  OTOH, I don't see any immediate need to expand the parameters
123       given to the "log" method.
124
125       Log Levels
126
127       The log levels that Log::Dispatch uses are taken directly from the sys‐
128       log man pages (except that I expanded them to full words).  Valid lev‐
129       els are:
130
131        debug
132        info
133        notice
134        warning
135        error
136        critical
137        alert
138        emergency
139
140       Alternately, the numbers 0 through 7 may be used (debug is 0 and emer‐
141       gency is 7).  The syslog standard of 'err', 'crit', and 'emerg' is also
142       acceptable.
143

USAGE

145       This module is designed to be used as a one-stop logging system.  In
146       particular, it was designed to be easy to subclass so that if you want
147       to handle messaging in a way not implemented in this package, you
148       should be able to add this with minimal effort.
149
150       The basic idea behind Log::Dispatch is that you create a Log::Dispatch
151       object and then add various logging objects to it (such as a file log‐
152       ger or screen logger).  Then you call the "log" method of the dispatch
153       object, which passes the message to each of the objects, which in turn
154       decide whether or not to accept the message and what to do with it.
155
156       This makes it possible to call single method and send a message to a
157       log file, via email, to the screen, and anywhere else, all with very
158       little code needed on your part, once the dispatching object has been
159       created.
160
161       The logging levels that Log::Dispatch uses are borrowed from the stan‐
162       dard UNIX syslog levels, except that where syslog uses partial words
163       ("err") Log::Dispatch also allows the use of the full word as well
164       ("error").
165
166       Making your own logging objects
167
168       Making your own logging object is generally as simple as subclassing
169       Log::Dispatch::Output and overriding the "new" and "log" methods.  See
170       the Log::Dispatch::Output docs for more details.
171
172       If you would like to create your own subclass for sending email then it
173       is even simpler.  Simply subclass Log::Dispatch::Email and override the
174       "send_email" method.  See the Log::Dispatch::Email docs for more
175       details.
176
177       Why doesn't Log::Dispatch add a newline to the message?
178
179       A few people have written email to me asking me to add something that
180       would tack a newline onto the end of all messages that don't have one.
181       This will never happen.  There are several reasons for this.  First of
182       all, Log::Dispatch was designed as a simple system to broadcast a mes‐
183       sage to multiple outputs.  It does not attempt to understand the mes‐
184       sage in any way at all.  Adding a newline implies an attempt to under‐
185       stand something about the message and I don't want to go there.  Sec‐
186       ondly, this is not very cross-platform and I don't want to go down the
187       road of testing Config values to figure out what to tack onto messages
188       based on OS.
189
190       I think people's desire to do this is because they are too focused on
191       just the logging to files aspect of this module.  In this case newlines
192       make sense.  However, imagine someone is using this module to log to a
193       remote server and the interactions between the client and server use
194       newlines as part of the control flow.  Casually adding a newline could
195       cause serious problems.
196
197       However, the 1.2 release adds the callbacks parameter for the Log::Dis‐
198       patch object which you can easily use to add newlines to messages if
199       you so desire.
200

RELATED MODULES

202       Log::Dispatch::DBI
203
204       Written by Tatsuhiko Miyagawa.  Log output to a database table.
205
206       Log::Dispatch::FileRotate
207
208       Written by Mark Pfeiffer.  Rotates log files periodically as part of
209       its usage.
210
211       Log::Dispatch::File::Stamped
212
213       Written by Eric Cholet.  Stamps log files with date and time informa‐
214       tion.
215
216       Log::Dispatch::Jabber
217
218       Written by Aaron Straup Cope.  Logs messages via Jabber.
219
220       Log::Dispatch::Tk
221
222       Written by Dominique Dumont.  Logs messages to a Tk window.
223
224       Log::Dispatch::Win32EventLog
225
226       Written by Arthur Bergman.  Logs messages to the Windows event log.
227
228       Log::Log4perl
229
230       An implementation of Java's log4j API in Perl, using Log::Dispatch to
231       do the actual logging.  Created by Mike Schilli and Kevin Goess.
232
233       Log::Dispatch::Config
234
235       Written by Tatsuhiko Miyagawa.  Allows configuration of logging via a
236       text file similar (or so I'm told) to how it is done with log4j.  Sim‐
237       pler than Log::Log4perl.
238
239       Log::Agent
240
241       A very different API for doing many of the same things that Log::Dis‐
242       patch does.  Originally written by Raphael Manfredi.
243

SUPPORT

245       Please submit bugs and patches to the CPAN RT system at
246       http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Log%3A%3ADispatch or via
247       email at bug-log-dispatch@rt.cpan.org.
248
249       Support questions can be sent to me at my email address, shown below.
250
251       The code repository is at https://svn.urth.org/svn/Log-Dispatch/
252

AUTHOR

254       Dave Rolsky, <autarch@urth.org>
255

COPYRIGHT

257       Copyright (c) 1999-2006 David Rolsky.  All rights reserved.  This pro‐
258       gram is free software; you can redistribute it and/or modify it under
259       the same terms as Perl itself.
260
261       The full text of the license can be found in the LICENSE file included
262       with this module.
263