======================================================================== * README.md ======================================================================== # NAME Log::Dispatch - Dispatches messages to one or more outputs # VERSION version 2.70 # SYNOPSIS use Log::Dispatch; # Simple API # my $log = Log::Dispatch->new( outputs => [ [ 'File', min_level => 'debug', filename => 'logfile' ], [ 'Screen', min_level => 'warning' ], ], ); $log->info('Blah, blah'); # More verbose API # my $log = Log::Dispatch->new(); $log->add( Log::Dispatch::File->new( name => 'file1', min_level => 'debug', filename => 'logfile' ) ); $log->add( Log::Dispatch::Screen->new( name => 'screen', min_level => 'warning', ) ); $log->log( level => 'info', message => 'Blah, blah' ); my $sub = sub { my %p = @_; return reverse $p{message}; }; my $reversing_dispatcher = Log::Dispatch->new( callbacks => $sub ); # DESCRIPTION This module manages a set of Log::Dispatch::\* output objects that can be logged to via a unified interface. The idea is that you create a Log::Dispatch object and then add various logging objects to it (such as a file logger or screen logger). Then you call the `log` method of the dispatch object, which passes the message to each of the objects, which in turn decide whether or not to accept the message and what to do with it. This makes it possible to call single method and send a message to a log file, via email, to the screen, and anywhere else, all with very little code needed on your part, once the dispatching object has been created. # METHODS This class provides the following methods: ## Log::Dispatch->new(...) This method takes the following parameters: - outputs( \[ \[ class, params, ... \], \[ class, params, ... \], ... \] ) This parameter is a reference to a list of lists. Each inner list consists of a class name and a set of constructor params. The class is automatically prefixed with 'Log::Dispatch::' unless it begins with '+', in which case the string following '+' is taken to be a full classname. e.g. outputs => [ [ 'File', min_level => 'debug', filename => 'logfile' ], [ '+My::Dispatch', min_level => 'info' ] ] For each inner list, a new output object is created and added to the dispatcher (via the `add()` method). See ["OUTPUT CLASSES"](#output-classes) for the parameters that can be used when creating an output object. - callbacks( \\& or \[ \\&, \\&, ... \] ) This parameter may be a single subroutine reference or an array reference of subroutine references. These callbacks will be called in the order they are given and passed a hash containing the following keys: ( message => $log_message, level => $log_level ) In addition, any key/value pairs passed to a logging method will be passed onto your callback. The callbacks are expected to modify the message and then return a single scalar containing that modified message. These callbacks will be called when either the `log` or `log_to` methods are called and will only be applied to a given message once. If they do not return the message then you will get no output. Make sure to return the message! ## $dispatch->clone() This returns a _shallow_ clone of the original object. The underlying output objects and callbacks are shared between the two objects. However any changes made to the outputs or callbacks that the object contains are not shared. ## $dispatch->log( level => $, message => $ or \\& ) Sends the message (at the appropriate level) to all the output objects that the dispatcher contains (by calling the `log_to` method repeatedly). The level can be specified by name or by an integer from 0 (debug) to 7 (emergency). This method also accepts a subroutine reference as the message argument. This reference will be called only if there is an output that will accept a message of the specified level. ## $dispatch->debug (message), info (message), ... You may call any valid log level (including valid abbreviations) as a method with a single argument that is the message to be logged. This is converted into a call to the `log` method with the appropriate level. For example: $log->alert('Strange data in incoming request'); translates to: $log->log( level => 'alert', message => 'Strange data in incoming request' ); If you pass an array to these methods, it will be stringified as is: my @array = ('Something', 'bad', 'is', 'here'); $log->alert(@array); # is equivalent to $log->alert("@array"); You can also pass a subroutine reference, just like passing one to the `log()` method. ## $dispatch->log\_and\_die( level => $, message => $ or \\& ) Has the same behavior as calling `log()` but calls `_die_with_message()` at the end. You can throw exception objects by subclassing this method. If the `carp_level` parameter is present its value will be added to the current value of `$Carp::CarpLevel`. ## $dispatch->log\_and\_croak( level => $, message => $ or \\& ) A synonym for `$dispatch-`log\_and\_die()>. ## $dispatch->log\_to( name => $, level => $, message => $ ) Sends the message only to the named object. Note: this will not properly handle a subroutine reference as the message. ## $dispatch->add\_callback( $code ) Adds a callback (like those given during construction). It is added to the end of the list of callbacks. Note that this can also be called on individual output objects. ## $dispatch->remove\_callback( $code ) Remove the given callback from the list of callbacks. Note that this can also be called on individual output objects. ## $dispatch->callbacks() Returns a list of the callbacks in a given output. ## $dispatch->level\_is\_valid( $string ) Returns true or false to indicate whether or not the given string is a valid log level. Can be called as either a class or object method. ## $dispatch->would\_log( $string ) Given a log level, returns true or false to indicate whether or not anything would be logged for that log level. ## $dispatch->is\_`$level` There are methods for every log level: `is_debug()`, `is_warning()`, etc. This returns true if the logger will log a message at the given level. ## $dispatch->add( Log::Dispatch::\* OBJECT ) Adds a new [output object](#output-classes) to the dispatcher. If an object of the same name already exists, then that object is replaced, with a warning if `$^W` is true. ## $dispatch->remove($) Removes the output object that matches the name given to the remove method. The return value is the object being removed or undef if no object matched this. ## $dispatch->outputs() Returns a list of output objects. ## $dispatch->output( $name ) Returns the output object of the given name. Returns undef or an empty list, depending on context, if the given output does not exist. ## $dispatch->\_die\_with\_message( message => $, carp\_level => $ ) This method is used by `log_and_die` and will either die() or croak() depending on the value of `message`: if it's a reference or it ends with a new line then a plain die will be used, otherwise it will croak. # OUTPUT CLASSES An output class - e.g. [Log::Dispatch::File](https://metacpan.org/pod/Log%3A%3ADispatch%3A%3AFile) or [Log::Dispatch::Screen](https://metacpan.org/pod/Log%3A%3ADispatch%3A%3AScreen) - implements a particular way of dispatching logs. Many output classes come with this distribution, and others are available separately on CPAN. The following common parameters can be used when creating an output class. All are optional. Most output classes will have additional parameters beyond these, see their documentation for details. - name ($) A name for the object (not the filename!). This is useful if you want to refer to the object later, e.g. to log specifically to it or remove it. By default a unique name will be generated. You should not depend on the form of generated names, as they may change. - min\_level ($) The minimum [logging level](#log-levels) this object will accept. Required. - max\_level ($) The maximum [logging level](#log-levels) this object will accept. By default the maximum is the highest possible level (which means functionally that the object has no maximum). - callbacks( \\& or \[ \\&, \\&, ... \] ) This parameter may be a single subroutine reference or an array reference of subroutine references. These callbacks will be called in the order they are given and passed a hash containing the following keys: ( message => $log_message, level => $log_level ) The callbacks are expected to modify the message and then return a single scalar containing that modified message. These callbacks will be called when either the `log` or `log_to` methods are called and will only be applied to a given message once. If they do not return the message then you will get no output. Make sure to return the message! - newline (0|1) If true, a callback will be added to the end of the callbacks list that adds a newline to the end of each message. Default is false, but some output classes may decide to make the default true. # LOG LEVELS The log levels that Log::Dispatch uses are taken directly from the syslog man pages (except that I expanded them to full words). Valid levels are: - debug - info - notice - warning - error - critical - alert - emergency Alternately, the numbers 0 through 7 may be used (debug is 0 and emergency is 7). The syslog standard of 'err', 'crit', and 'emerg' is also acceptable. We also allow 'warn' as a synonym for 'warning'. # SUBCLASSING This module was designed to be easy to subclass. If you want to handle messaging in a way not implemented in this package, you should be able to add this with minimal effort. It is generally as simple as subclassing Log::Dispatch::Output and overriding the `new` and `log_message` methods. See the [Log::Dispatch::Output](https://metacpan.org/pod/Log%3A%3ADispatch%3A%3AOutput) docs for more details. If you would like to create your own subclass for sending email then it is even simpler. Simply subclass [Log::Dispatch::Email](https://metacpan.org/pod/Log%3A%3ADispatch%3A%3AEmail) and override the `send_email` method. See the [Log::Dispatch::Email](https://metacpan.org/pod/Log%3A%3ADispatch%3A%3AEmail) docs for more details. The logging levels that Log::Dispatch uses are borrowed from the standard UNIX syslog levels, except that where syslog uses partial words ("err") Log::Dispatch also allows the use of the full word as well ("error"). # RELATED MODULES ## Log::Dispatch::DBI Written by Tatsuhiko Miyagawa. Log output to a database table. ## Log::Dispatch::FileRotate Written by Mark Pfeiffer. Rotates log files periodically as part of its usage. ## Log::Dispatch::File::Stamped Written by Eric Cholet. Stamps log files with date and time information. ## Log::Dispatch::Jabber Written by Aaron Straup Cope. Logs messages via Jabber. ## Log::Dispatch::Tk Written by Dominique Dumont. Logs messages to a Tk window. ## Log::Dispatch::Win32EventLog Written by Arthur Bergman. Logs messages to the Windows event log. ## Log::Log4perl An implementation of Java's log4j API in Perl. Log messages can be limited by fine-grained controls, and if they end up being logged, both native Log4perl and Log::Dispatch appenders can be used to perform the actual logging job. Created by Mike Schilli and Kevin Goess. ## Log::Dispatch::Config Written by Tatsuhiko Miyagawa. Allows configuration of logging via a text file similar (or so I'm told) to how it is done with log4j. Simpler than Log::Log4perl. ## Log::Agent A very different API for doing many of the same things that Log::Dispatch does. Originally written by Raphael Manfredi. # SEE ALSO [Log::Dispatch::ApacheLog](https://metacpan.org/pod/Log%3A%3ADispatch%3A%3AApacheLog), [Log::Dispatch::Email](https://metacpan.org/pod/Log%3A%3ADispatch%3A%3AEmail), [Log::Dispatch::Email::MailSend](https://metacpan.org/pod/Log%3A%3ADispatch%3A%3AEmail%3A%3AMailSend), [Log::Dispatch::Email::MailSender](https://metacpan.org/pod/Log%3A%3ADispatch%3A%3AEmail%3A%3AMailSender), [Log::Dispatch::Email::MailSendmail](https://metacpan.org/pod/Log%3A%3ADispatch%3A%3AEmail%3A%3AMailSendmail), [Log::Dispatch::Email::MIMELite](https://metacpan.org/pod/Log%3A%3ADispatch%3A%3AEmail%3A%3AMIMELite), [Log::Dispatch::File](https://metacpan.org/pod/Log%3A%3ADispatch%3A%3AFile), [Log::Dispatch::File::Locked](https://metacpan.org/pod/Log%3A%3ADispatch%3A%3AFile%3A%3ALocked), [Log::Dispatch::Handle](https://metacpan.org/pod/Log%3A%3ADispatch%3A%3AHandle), [Log::Dispatch::Output](https://metacpan.org/pod/Log%3A%3ADispatch%3A%3AOutput), [Log::Dispatch::Screen](https://metacpan.org/pod/Log%3A%3ADispatch%3A%3AScreen), [Log::Dispatch::Syslog](https://metacpan.org/pod/Log%3A%3ADispatch%3A%3ASyslog) # SUPPORT Bugs may be submitted at [https://github.com/houseabsolute/Log-Dispatch/issues](https://github.com/houseabsolute/Log-Dispatch/issues). I am also usually active on IRC as 'autarch' on `irc://irc.perl.org`. # SOURCE The source code repository for Log-Dispatch can be found at [https://github.com/houseabsolute/Log-Dispatch](https://github.com/houseabsolute/Log-Dispatch). # DONATIONS If you'd like to thank me for the work I've done on this module, please consider making a "donation" to me via PayPal. I spend a lot of free time creating free software, and would appreciate any support you'd care to offer. Please note that **I am not suggesting that you must do this** in order for me to continue working on this particular software. I will continue to do so, inasmuch as I have in the past, for as long as it interests me. Similarly, a donation made in this way will probably not make me work on this software much more, unless I get so many donations that I can consider working on free software full time (let's all have a chuckle at that together). To donate, log into PayPal and send money to autarch@urth.org, or use the button at [https://www.urth.org/fs-donation.html](https://www.urth.org/fs-donation.html). # AUTHOR Dave Rolsky # CONTRIBUTORS - Anirvan Chatterjee - Carsten Grohmann - Doug Bell - Graham Knop - Graham Ollis - Gregory Oschwald - hartzell - Joelle Maslak - Johann Rolschewski - Jonathan Swartz - Karen Etheridge - Kerin Millar - Kivanc Yazan - Konrad Bucheli - Michael Schout - Olaf Alders - Olivier Mengué - Rohan Carly - Ross Attrill - Salvador Fandiño - Sergey Leschenko - Slaven Rezic - Steve Bertrand - Whitney Jackson # COPYRIGHT AND LICENSE This software is Copyright (c) 2020 by Dave Rolsky. This is free software, licensed under: The Artistic License 2.0 (GPL Compatible) The full text of the license can be found in the `LICENSE` file included with this distribution. ======================================================================== * LICENSE ======================================================================== This software is Copyright (c) 2020 by Dave Rolsky. This is free software, licensed under: The Artistic License 2.0 (GPL Compatible) The Artistic License 2.0 Copyright (c) 2000-2006, The Perl Foundation. Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Preamble This license establishes the terms under which a given free software Package may be copied, modified, distributed, and/or redistributed. The intent is that the Copyright Holder maintains some artistic control over the development of that Package while still keeping the Package available as open source and free software. You are always permitted to make arrangements wholly outside of this license directly with the Copyright Holder of a given Package. If the terms of this license do not permit the full use that you propose to make of the Package, you should contact the Copyright Holder and seek a different licensing arrangement. Definitions "Copyright Holder" means the individual(s) or organization(s) named in the copyright notice for the entire Package. "Contributor" means any party that has contributed code or other material to the Package, in accordance with the Copyright Holder's procedures. "You" and "your" means any person who would like to copy, distribute, or modify the Package. "Package" means the collection of files distributed by the Copyright Holder, and derivatives of that collection and/or of those files. A given Package may consist of either the Standard Version, or a Modified Version. "Distribute" means providing a copy of the Package or making it accessible to anyone else, or in the case of a company or organization, to others outside of your company or organization. "Distributor Fee" means any fee that you charge for Distributing this Package or providing support for this Package to another party. It does not mean licensing fees. "Standard Version" refers to the Package if it has not been modified, or has been modified only in ways explicitly requested by the Copyright Holder. "Modified Version" means the Package, if it has been changed, and such changes were not explicitly requested by the Copyright Holder. "Original License" means this Artistic License as Distributed with the Standard Version of the Package, in its current version or as it may be modified by The Perl Foundation in the future. "Source" form means the source code, documentation source, and configuration files for the Package. "Compiled" form means the compiled bytecode, object code, binary, or any other form resulting from mechanical transformation or translation of the Source form. Permission for Use and Modification Without Distribution (1) You are permitted to use the Standard Version and create and use Modified Versions for any purpose without restriction, provided that you do not Distribute the Modified Version. Permissions for Redistribution of the Standard Version (2) You may Distribute verbatim copies of the Source form of the Standard Version of this Package in any medium without restriction, either gratis or for a Distributor Fee, provided that you duplicate all of the original copyright notices and associated disclaimers. At your discretion, such verbatim copies may or may not include a Compiled form of the Package. (3) You may apply any bug fixes, portability changes, and other modifications made available from the Copyright Holder. The resulting Package will still be considered the Standard Version, and as such will be subject to the Original License. Distribution of Modified Versions of the Package as Source (4) You may Distribute your Modified Version as Source (either gratis or for a Distributor Fee, and with or without a Compiled form of the Modified Version) provided that you clearly document how it differs from the Standard Version, including, but not limited to, documenting any non-standard features, executables, or modules, and provided that you do at least ONE of the following: (a) make the Modified Version available to the Copyright Holder of the Standard Version, under the Original License, so that the Copyright Holder may include your modifications in the Standard Version. (b) ensure that installation of your Modified Version does not prevent the user installing or running the Standard Version. In addition, the Modified Version must bear a name that is different from the name of the Standard Version. (c) allow anyone who receives a copy of the Modified Version to make the Source form of the Modified Version available to others under (i) the Original License or (ii) a license that permits the licensee to freely copy, modify and redistribute the Modified Version using the same licensing terms that apply to the copy that the licensee received, and requires that the Source form of the Modified Version, and of any works derived from it, be made freely available in that license fees are prohibited but Distributor Fees are allowed. Distribution of Compiled Forms of the Standard Version or Modified Versions without the Source (5) You may Distribute Compiled forms of the Standard Version without the Source, provided that you include complete instructions on how to get the Source of the Standard Version. Such instructions must be valid at the time of your distribution. If these instructions, at any time while you are carrying out such distribution, become invalid, you must provide new instructions on demand or cease further distribution. If you provide valid instructions or cease distribution within thirty days after you become aware that the instructions are invalid, then you do not forfeit any of your rights under this license. (6) You may Distribute a Modified Version in Compiled form without the Source, provided that you comply with Section 4 with respect to the Source of the Modified Version. Aggregating or Linking the Package (7) You may aggregate the Package (either the Standard Version or Modified Version) with other packages and Distribute the resulting aggregation provided that you do not charge a licensing fee for the Package. Distributor Fees are permitted, and licensing fees for other components in the aggregation are permitted. The terms of this license apply to the use and Distribution of the Standard or Modified Versions as included in the aggregation. (8) You are permitted to link Modified and Standard Versions with other works, to embed the Package in a larger work of your own, or to build stand-alone binary or bytecode versions of applications that include the Package, and Distribute the result without restriction, provided the result does not expose a direct interface to the Package. Items That are Not Considered Part of a Modified Version (9) Works (including, but not limited to, modules and scripts) that merely extend or make use of the Package, do not, by themselves, cause the Package to be a Modified Version. In addition, such works are not considered parts of the Package itself, and are not subject to the terms of this license. General Provisions (10) Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license. (11) If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license. (12) This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder. (13) This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed. (14) Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.