Tatsuhiko Miyagawa > Log-Dispatch-Config-1.04 > Log::Dispatch::Config

Download:
Log-Dispatch-Config-1.04.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  4
Open  2
View/Report Bugs
Module Version: 1.04   Source  

NAME ^

Log::Dispatch::Config - Log4j for Perl

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 ^

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.

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, 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 ^

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 differenct argument.

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 ^

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

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 match against /^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, POE::Component::Logger

syntax highlighting: