/ 
Log-Dispatch-Config-0.09
River stage two • 12 direct dependents • 21 total dependents
/ Log::Dispatch::Config

NAME

Log::Dispatch::Config - Log4j for Perl

SYNOPSIS

use Log::Dispatch::Config;
Log::Dispatch::Config->configure('/path/to/config');

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

# or the same
my $dispatcher = Log::Dispatch->instance;

# 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

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

METHOD

This module has a class method configure which parses config file for later creation of the Log::Dispatch::Config singleton 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 startup.pl in mod_perl), then you can get configured dispatcher instance via Log::Dispatch::Config->instance.

Formerly, configure method declares instance method in Log::Dispatch namespace. Now it inherits from Log::Dispatch, so the namespace pollution is not necessary. Currrent version still defines one-liner shortcut:

sub Log::Dispatch::instance { Log::Dispatch::Config->instance }

so still you can call Log::Dispatch->instance, if you prefer, or for backward compatibility.

CONFIGURATION

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.

GLOBAL PARAMETERS

dispatchers
dispatchers = file screen

dispatchers defines logger names, which will be splitted by spaces. If this parameter is unset, no logging is done.

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

format defines log format. Possible conversions format are

%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

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:

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

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

class
screen.class = Log::Dispatch::Screen

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

format
screen.format = -- %m --

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

(others)
screen.min_level = info
screen.stderr = 1

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

SINGLETON

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, Singleton instance is not so useful. Log::Dispatch::Config defines instance method so that the object reloads itself when configuration file is modified since its last object creation time.

PLUGGABLE CONFIGURATOR

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

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. Stub new constructor is inherited, but you can roll your own with it.

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

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 accepts Log::Dispatch::Config instance and should return boolean value if the object is stale and needs reloading itself.

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

    sub needs_reload {
    my($self, $obj) = @_;
    return $obj->{ctime} < (stat($self->{file}))[9];
}

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

    sub needs_reload { 1 }

    reload method is called when needs_reload returns true, and should return new Configurator instance. Typically you should place configuration parsing again on this method, so Log::Dispatch::Configurator again declares stub reload method that clones your object.

    sub reload {
    my $self = shift;
    my $class = ref $self;
    return $class->new($self->{file});
}

  • 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;
use Log::Dispatch::Configurator::Hardwired;

my $config = Log::Dispatch::Configurator::Hardwired->new;
Log::Dispatch::Config->configure($config);

CALLER STACK

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) = @_;
    $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 begin with /^Log::Dispatch/, which makes this module confusing.

AUTHOR

Tatsuhiko Miyagawa <miyagawa@bulknews.net> with much help from Matt Sergeant <matt@sergeant.org>.

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

SEE ALSO

Log::Dispatch::Configurator::AppConfig, Log::Dispatch, AppConfig