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; # or the same (may be deprecated) my $dispatcher = Log::Dispatch->instance; DESCRIPTION Log::Dispatch::Config is a subclass of Log::Dispatch and provides a way to configure Log::Dispatch object with configulation file (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 Config file is parsed with AppConfig module, see the AppConfig manpage when you face configuration parsing error. 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 = [${datetime}] [${prioity}] ${message} at ${filename} line ${line}\n `format' defines log format. `%X' style and `${XXX}' style are both supported. Possible conversions format are %d ${datetime} datetime string %p ${priority} priority (debug, info, warning ...) %m ${message} message string %F ${filename} filename %L ${line} line number %P ${package} package %n newline (\n) `format' defined here would apply to all the log messages to dispatchers. This parameter is optional. 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. 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. TODO * LogLevel configuration depending on caller package like log4j? AUTHOR Tatsuhiko Miyagawa This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO the Log::Dispatch manpage, the AppConfig manpage