Filewatcher File Search File Search
Content Search
» » » » » » perl-Log-Dispatch-Config-1.02-1.el5.rf.noarch.rpm » Content »
pkg://perl-Log-Dispatch-Config-1.02-1.el5.rf.noarch.rpm:24247/usr/share/man/man3/  info  HEADER  downloads

perl-Log-Dispatch-Config - Perl module that implements Log4j…  more info»


Log::Dispatch::CoUser(Contributed Perl DocumLog::Dispatch::Config(3)

       Log::Dispatch::Config - Log4j for Perl

         use Log::Dispatch::Config;

         my $dispatcher = Log::Dispatch::Config->instance;
         $dispatcher->debug('this is debug message');
         $dispatcher->emergency('something *bad* happened!');

         # automatic reloading conf file, when modified

         # or if you write your own config parser:
         use Log::Dispatch::Configurator::XMLSimple;

         my $config = Log::Dispatch::Configurator::XMLSimple->new('log.xml');

       Log::Dispatch::Config is a subclass of Log::Dispatch and pro‐
       vides a way to configure Log::Dispatch object with configula‐
       tion file (default, in AppConfig format). I mean, this is
       log4j for Perl, not with all API compatibility though.

       This module has a class method "configure" which parses con‐
       fig file for later creation of the Log::Dispatch::Config sin‐
       gleton instance.  (Actual construction of the object is done
       in the first "instance" call).

       So, what you should do is call "configure" method once in
       somewhere (like "" in mod_perl), then you can get
       configured dispatcher instance via "Log::Dispatch::Con‐

       Here is an example of the config file:

         dispatchers = file screen

         file.class = Log::Dispatch::File
         file.min_level = debug
         file.filename = /path/to/log
         file.mode = append
         file.format = [%d] [%p] %m at %F line %L%n

         screen.class = Log::Dispatch::Screen
         screen.min_level = info
         screen.stderr = 1
         screen.format = %m

       In this example, config file is written in AppConfig format.
       See Log::Dispatch::Configurator::AppConfig for details.

       See "PLUGGABLE CONFIGURATOR" for other config parsing scheme.


             dispatchers = file screen

           "dispatchers" defines logger names, which will be split‐
           ted by spaces.  If this parameter is unset, no logging is

             format = [%d] [%p] %m at %F line %L%n

           "format" defines log format. Possible conversions format

             %d    datetime string (ctime(3))
             %p    priority (debug, info, warning ...)
             %m    message string
             %F    filename
             %L    line number
             %P    package
             %n    newline (\n)
             %%    % itself

           Note that datetime (%d) format is configurable by passing
           "strftime" fmt in braket after %d. (I know it looks quite
           messy, but its compatible with Java Log4j ;)

             format = [%d{%Y%m%d}] %m  # datetime is now strftime "%Y%m%d"

           If you have Time::Piece, this module uses its "strftime"
           implementation, otherwise POSIX.

           "format" defined here would apply to all the log messages
           to dispatchers. This parameter is optional.

           See "CALLER STACK" for details about package, line number
           and filename.


       Parameters for each dispatcher should be prefixed with
       "name.", where "name" is the name of each one, defined in
       global "dispatchers" parameter.

       You can also use ".ini" style grouping like:

         class = Log::Dispatch::File
         min_level = debug

       See Log::Dispatch::Configurator::AppConfig for details.

             screen.class = Log::Dispatch::Screen

           "class" defines class name of Log::Dispatch subclasses.
           This parameter is essential.

             screen.format = -- %m --

           "format" defines log format which would be applied only
           to the dispatcher. Note that if you define global "for‐
           mat" also, %m is double formated (first global one, next
           each dispatcher one). This parameter is optional.

             screen.min_level = info
             screen.stderr = 1

           Other parameters would be passed to the each dispatcher
           construction. See Log::Dispatch::* manpage for the

       Declared "instance" method would make "Log::Dispatch::Config"
       class singleton, so multiple calls of "instance" will all
       result in returning same object.

         my $one = Log::Dispatch::Config->instance;
         my $two = Log::Dispatch::Config->instance; # same as $one

       See GoF Design Pattern book for Singleton Pattern.

       But in practice, in persistent environment like mod_perl,
       lifetime of Singleton instance becomes sometimes messy. If
       you want to reload singleton object manually, call "reload"


       And, if you want to reload object on the fly, as you edit
       "log.conf" or something like that, what you should do is to
       call "configure_and_watch" method on Log::Dispatch::Config
       instead of "configure". Then "instance" call will check mtime
       of configuration file, and compares it with instanciation
       time of singleton object. If config file is newer than last
       instanciation, it will automatically reload object.

       If you use Log::Dispatch::Config in multiple projects on the
       same perl interpreter (like mod_perl), namespace collision
       would be a problem. Bizzare thing will happen when you call
       "Log::Dispatch::Config->configure" multiple times with dif‐
       ferenct argument.

       In such cases, what you should do is to define your own log‐
       ger class.

         package My::Logger;
         use Log::Dispatch::Config;
         use base qw(Log::Dispatch::Config);

       Or make wrapper for it. See POE::Component::Logger implemen‐
       tation by Matt Sergeant.

       If you pass filename to "configure" method call, this module
       handles the config file with AppConfig. You can change config
       parsing scheme by passing another pluggable configurator

       Here is a way to declare new configurator class. The example
       below is hardwired version equivalent to the one above in

       ·   Inherit from Log::Dispatch::Configurator.

             package Log::Dispatch::Configurator::Hardwired;
             use base qw(Log::Dispatch::Configurator);

           Declare your own "new" constructor. Stub "new" method is
           defined in Configurator base class, but you want to put
           parsing method in your own constructor. In this example,
           we just bless reference. Note that your object should be
           blessed hash.

             sub new { bless {}, shift }

       ·   Implement two required object methods "get_attrs_global"
           and "get_attrs".

           "get_attrs_global" should return hash reference of global
           parameters.  "dispatchers" should be an array reference
           of names of dispatchers.

             sub get_attrs_global {
                 my $self = shift;
                 return {
                     format => undef,
                     dispatchers => [ qw(file screen) ],

           "get_attrs" accepts name of a dispatcher and should
           return hash reference of parameters associated with the

             sub get_attrs {
                 my($self, $name) = @_;
                 if ($name eq 'file') {
                     return {
                         class     => 'Log::Dispatch::File',
                         min_level => 'debug',
                         filename  => '/path/to/log',
                         mode      => 'append',
                         format  => '[%d] [%p] %m at %F line %L%n',
                 elsif ($name eq 'screen') {
                     return {
                         class     => 'Log::Dispatch::Screen',
                         min_level => 'info',
                         stderr    => 1,
                         format  => '%m',
                 else {
                     die "invalid dispatcher name: $name";

       ·   Implement optional "needs_reload" and "reload" methods.
           "needs_reload" should return boolean value if the object
           is stale and needs reloading itself. This method will be
           triggered when you configure logging object with "config‐
           ure_and_watch" method.

           Stub config file mtime based "needs_reload" method is
           declared in Log::Dispatch::Configurator, so if your con‐
           fig class is based on filesystem files, you do not need
           to reimplement this.

           If you do not need singleton-ness at all, always return

             sub needs_reload { 1 }

           "reload" method should redo parsing of the config file.
           Configurator base class has a stub null "reload" method,
           so you should better override it.

           See Log::Dispatch::Configurator::AppConfig source code
           for details.

       ·   That's all. Now you can plug your own configurator (Hard‐
           wired) into Log::Dispatch::Config. What you should do is
           to pass configurator object to "configure" method call
           instead of config file name.

             use Log::Dispatch::Config;
             use Log::Dispatch::Configurator::Hardwired;

             my $config = Log::Dispatch::Configurator::Hardwired->new;

       When you call logging method from your subroutines / methods,
       caller stack would increase and thus you can't see where the
       log really comes from.

         package Logger;
         my $Logger = Log::Dispatch::Config->instance;

         sub logit {
             my($class, $level, $msg) = @_;

         package main;
         Logger->logit('debug', 'foobar');

       You can adjust package variable $Log::Dispatch::Con‐
       fig::CallerDepth to increase the caller stack depth. The
       default value is 0.

         sub logit {
             my($class, $level, $msg) = @_;
             local $Log::Dispatch::Config::CallerDepth = 1;

       Note that your log caller's namespace should not match
       against "/^Log::Dispatch/", which makes this module confus‐

       Tatsuhiko Miyagawa <> with much help
       from Matt Sergeant <>.

       This library is free software; you can redistribute it and/or
       modify it under the same terms as Perl itself.

       Log::Dispatch::Configurator::AppConfig, Log::Dispatch, App‐
       Config, POE::Component::Logger

perl v5.8.8                  2007-08-08     Log::Dispatch::Config(3)
Results 1 - 1 of 1
Help - FTP Sites List - Software Dir.
Search over 15 billion files
© 1997-2017