NAME

SYNOPSIS

  use Log::Dispatch::Config;
  Log::Dispatch::Config->configure('/path/to/log.conf');

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

  # automatic reloading conf file, when modified
  Log::Dispatch::Config->configure_and_watch('/path/to/log.conf');

  # 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->configure($config);

DESCRIPTION

METHOD

So, what you should do is call "configure" method once in somewhere (like "startup.pl" in mod_perl), then you can get configured dispatcher instance via "Log::Dispatch::Config->instance".

CONFIGURATION

  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.

  [foo]
  class = Log::Dispatch::File
  min_level = debug

SINGLETON

  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" method.

  Log::Dispatch::Config->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.

NAMESPACE COLLISION

In such cases, what you should do is to define your own logger class.

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

Or make wrapper for it. See POE::Component::Logger implementation by Matt Sergeant.

PLUGGABLE CONFIGURATOR

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

• 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 dispatcher.

    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 "configure_and_watch" method.

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

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

    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 (Hardwired) 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;
    Log::Dispatch::Config->configure($config);
      

CALLER STACK

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

  sub logit {
      my($class, $level, $msg) = @_;
      $Logger->$level($msg);
  }

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

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

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

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

AUTHOR

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

SEE ALSO