| 1 |
NAME |
| 2 |
Log::Dispatch::Config - Log4j for Perl |
| 3 |
|
| 4 |
SYNOPSIS |
| 5 |
use Log::Dispatch::Config; |
| 6 |
Log::Dispatch::Config->configure('/path/to/log.conf'); |
| 7 |
|
| 8 |
my $dispatcher = Log::Dispatch::Config->instance; |
| 9 |
$dispatcher->debug('this is debug message'); |
| 10 |
$dispatcher->emergency('something *bad* happened!'); |
| 11 |
|
| 12 |
# or if you write your own config parser: |
| 13 |
use Log::Dispatch::Configurator::XMLSimple; |
| 14 |
|
| 15 |
my $config = Log::Dispatch::Configurator::XMLSimple->new('log.xml'); |
| 16 |
Log::Dispatch::Config->configure($config); |
| 17 |
|
| 18 |
# automatic reloading conf file, when modified |
| 19 |
Log::Dispatch::Config->configure_and_watch('/path/to/log.conf'); |
| 20 |
|
| 21 |
DESCRIPTION |
| 22 |
Log::Dispatch::Config is a subclass of Log::Dispatch and provides a way |
| 23 |
to configure Log::Dispatch object with configulation file (default, in |
| 24 |
AppConfig format). I mean, this is log4j for Perl, not with all API |
| 25 |
compatibility though. |
| 26 |
|
| 27 |
METHOD |
| 28 |
This module has a class method "configure" which parses config file for |
| 29 |
later creation of the Log::Dispatch::Config singleton instance. (Actual |
| 30 |
construction of the object is done in the first "instance" call). |
| 31 |
|
| 32 |
So, what you should do is call "configure" method once in somewhere |
| 33 |
(like "startup.pl" in mod_perl), then you can get configured dispatcher |
| 34 |
instance via "Log::Dispatch::Config->instance". |
| 35 |
|
| 36 |
Formerly, "configure" method declares "instance" method in Log::Dispatch |
| 37 |
namespace. Now it inherits from Log::Dispatch, so the namespace |
| 38 |
pollution is not necessary. Currrent version still defines one-liner |
| 39 |
shortcut: |
| 40 |
|
| 41 |
sub Log::Dispatch::instance { Log::Dispatch::Config->instance } |
| 42 |
|
| 43 |
so still you can call "Log::Dispatch->instance", if you prefer, or for |
| 44 |
backward compatibility. |
| 45 |
|
| 46 |
CONFIGURATION |
| 47 |
Here is an example of the config file: |
| 48 |
|
| 49 |
dispatchers = file screen |
| 50 |
|
| 51 |
file.class = Log::Dispatch::File |
| 52 |
file.min_level = debug |
| 53 |
file.filename = /path/to/log |
| 54 |
file.mode = append |
| 55 |
file.format = [%d] [%p] %m at %F line %L%n |
| 56 |
|
| 57 |
screen.class = Log::Dispatch::Screen |
| 58 |
screen.min_level = info |
| 59 |
screen.stderr = 1 |
| 60 |
screen.format = %m |
| 61 |
|
| 62 |
In this example, config file is written in AppConfig format. See the |
| 63 |
Log::Dispatch::Configurator::AppConfig manpage for details. |
| 64 |
|
| 65 |
See the section on "PLUGGABLE CONFIGURATOR" for other config parsing |
| 66 |
scheme. |
| 67 |
|
| 68 |
GLOBAL PARAMETERS |
| 69 |
|
| 70 |
dispatchers |
| 71 |
dispatchers = file screen |
| 72 |
|
| 73 |
"dispatchers" defines logger names, which will be splitted by |
| 74 |
spaces. If this parameter is unset, no logging is done. |
| 75 |
|
| 76 |
format |
| 77 |
format = [%d] [%p] %m at %F line %L%n |
| 78 |
|
| 79 |
"format" defines log format. Possible conversions format are |
| 80 |
|
| 81 |
%d datetime string (ctime(3)) |
| 82 |
%p priority (debug, info, warning ...) |
| 83 |
%m message string |
| 84 |
%F filename |
| 85 |
%L line number |
| 86 |
%P package |
| 87 |
%n newline (\n) |
| 88 |
%% % itself |
| 89 |
|
| 90 |
Note that datetime (%d) format is configurable by passing "strftime" |
| 91 |
fmt in braket after %d. (I know it looks quite messy, but its |
| 92 |
compatible with Java Log4j ;) |
| 93 |
|
| 94 |
format = [%d{%Y%m%d}] %m # datetime is now strftime "%Y%m%d" |
| 95 |
|
| 96 |
If you have Time::Piece, this module uses its "strftime" |
| 97 |
implementation, otherwise POSIX. |
| 98 |
|
| 99 |
"format" defined here would apply to all the log messages to |
| 100 |
dispatchers. This parameter is optional. |
| 101 |
|
| 102 |
See the section on "CALLER STACK" for details about package, line |
| 103 |
number and filename. |
| 104 |
|
| 105 |
PARAMETERS FOR EACH DISPATCHER |
| 106 |
|
| 107 |
Parameters for each dispatcher should be prefixed with "name.", where |
| 108 |
"name" is the name of each one, defined in global "dispatchers" |
| 109 |
parameter. |
| 110 |
|
| 111 |
You can also use ".ini" style grouping like: |
| 112 |
|
| 113 |
[foo] |
| 114 |
class = Log::Dispatch::File |
| 115 |
min_level = debug |
| 116 |
|
| 117 |
See the Log::Dispatch::Configurator::AppConfig manpage for details. |
| 118 |
|
| 119 |
class |
| 120 |
screen.class = Log::Dispatch::Screen |
| 121 |
|
| 122 |
"class" defines class name of Log::Dispatch subclasses. This |
| 123 |
parameter is essential. |
| 124 |
|
| 125 |
format |
| 126 |
screen.format = -- %m -- |
| 127 |
|
| 128 |
"format" defines log format which would be applied only to the |
| 129 |
dispatcher. Note that if you define global "format" also, %m is |
| 130 |
double formated (first global one, next each dispatcher one). This |
| 131 |
parameter is optional. |
| 132 |
|
| 133 |
(others) |
| 134 |
screen.min_level = info |
| 135 |
screen.stderr = 1 |
| 136 |
|
| 137 |
Other parameters would be passed to the each dispatcher |
| 138 |
construction. See Log::Dispatch::* manpage for the details. |
| 139 |
|
| 140 |
SINGLETON |
| 141 |
Declared "instance" method would make "Log::Dispatch::Config" class |
| 142 |
singleton, so multiple calls of "instance" will all result in returning |
| 143 |
same object. |
| 144 |
|
| 145 |
my $one = Log::Dispatch::Config->instance; |
| 146 |
my $two = Log::Dispatch::Config->instance; # same as $one |
| 147 |
|
| 148 |
See GoF Design Pattern book for Singleton Pattern. |
| 149 |
|
| 150 |
But in practice, in persistent environment like mod_perl, lifetime of |
| 151 |
Singleton instance becomes sometimes messy. If you want to reload |
| 152 |
singleton object manually, call "reload" method. |
| 153 |
|
| 154 |
Log::Dispatch::Config->reload; |
| 155 |
|
| 156 |
And, if you want to reload object on the fly, as you edit "log.conf" or |
| 157 |
something like that, what you should do is to call "configure_and_watch" |
| 158 |
method on Log::Dispatch::Config instead of "configure". Then "instance" |
| 159 |
call will check mtime of configuration file, and compares it with last |
| 160 |
configuration time. If config file is newer than last configuration, it |
| 161 |
will automatically reload object. |
| 162 |
|
| 163 |
NAMESPACE COLLISION |
| 164 |
If you use Log::Dispatch::Config in multiple projects on the same perl |
| 165 |
interpreter (like mod_perl), namespace collision would be a problem. |
| 166 |
Bizzare thing will happen when you call |
| 167 |
"Log::Dispatch::Config->configure" multiple times with differenct |
| 168 |
argument. |
| 169 |
|
| 170 |
In such cases, what you should do is to define your own logger class. |
| 171 |
|
| 172 |
package My::Logger; |
| 173 |
use Log::Dispatch::Config; |
| 174 |
use base qw(Log::Dispatch::Config); |
| 175 |
|
| 176 |
Or make wrapper for it. See the POE::Component::Logger manpage |
| 177 |
implementation by Matt. |
| 178 |
|
| 179 |
PLUGGABLE CONFIGURATOR |
| 180 |
If you pass filename to "configure" method call, this module handles the |
| 181 |
config file with AppConfig. You can change config parsing scheme by |
| 182 |
passing another pluggable configurator object. |
| 183 |
|
| 184 |
Here is a way to declare new configurator class. The example below is |
| 185 |
hardwired version equivalent to the one above in the section on |
| 186 |
"CONFIGURATION". |
| 187 |
|
| 188 |
* Inherit from Log::Dispatch::Configurator. |
| 189 |
|
| 190 |
package Log::Dispatch::Configurator::Hardwired; |
| 191 |
use base qw(Log::Dispatch::Configurator); |
| 192 |
|
| 193 |
* Implement two required object methods "get_attrs_global" and |
| 194 |
"get_attrs". |
| 195 |
|
| 196 |
"get_attrs_global" should return hash reference of global |
| 197 |
parameters. "dispatchers" should be an array reference of names of |
| 198 |
dispatchers. |
| 199 |
|
| 200 |
sub get_attrs_global { |
| 201 |
my $self = shift; |
| 202 |
return { |
| 203 |
format => undef, |
| 204 |
dispatchers => [ qw(file screen) ], |
| 205 |
}; |
| 206 |
} |
| 207 |
|
| 208 |
"get_attrs" accepts name of a dispatcher and should return hash |
| 209 |
reference of parameters associated with the dispatcher. |
| 210 |
|
| 211 |
sub get_attrs { |
| 212 |
my($self, $name) = @_; |
| 213 |
if ($name eq 'file') { |
| 214 |
return { |
| 215 |
class => 'Log::Dispatch::File', |
| 216 |
min_level => 'debug', |
| 217 |
filename => '/path/to/log', |
| 218 |
mode => 'append', |
| 219 |
format => '[%d] [%p] %m at %F line %L%n', |
| 220 |
}; |
| 221 |
} |
| 222 |
elsif ($name eq 'screen') { |
| 223 |
return { |
| 224 |
class => 'Log::Dispatch::Screen', |
| 225 |
min_level => 'info', |
| 226 |
stderr => 1, |
| 227 |
format => '%m', |
| 228 |
}; |
| 229 |
} |
| 230 |
else { |
| 231 |
die "invalid dispatcher name: $name"; |
| 232 |
} |
| 233 |
} |
| 234 |
|
| 235 |
* Implement optional "needs_reload" and "parse" methods. |
| 236 |
"needs_reload" should return boolean value if the object is stale |
| 237 |
and needs reloading itself. This method will be triggered when you |
| 238 |
configure logging object with "configure_and_watch" method. |
| 239 |
|
| 240 |
Stub config file mtime based "needs_reload" method is declared in |
| 241 |
Log::Dispatch::Configurator as below, so if your config class is |
| 242 |
based on filesystem files, you do not need to reimplement this. |
| 243 |
|
| 244 |
sub needs_reload { |
| 245 |
my($self, $obj) = @_; |
| 246 |
return $obj->{ctime} < (stat($self->{file}))[9]; |
| 247 |
} |
| 248 |
|
| 249 |
If you do not need *singleton-ness at all*, always return true. |
| 250 |
|
| 251 |
sub needs_reload { 1 } |
| 252 |
|
| 253 |
"parse" method should do parsing of the config file. This method is |
| 254 |
called in the first parsing of the config file, and again when |
| 255 |
"needs_reload" returns true. Log::Dispatch::Configurator base class |
| 256 |
has a null "parse" method. |
| 257 |
|
| 258 |
* That's all. Now you can plug your own configurator (Hardwired) into |
| 259 |
Log::Dispatch::Config. What you should do is to pass configurator |
| 260 |
object to "configure" method call instead of config file name. |
| 261 |
|
| 262 |
use Log::Dispatch; |
| 263 |
use Log::Dispatch::Configurator::Hardwired; |
| 264 |
|
| 265 |
my $config = Log::Dispatch::Configurator::Hardwired->new; |
| 266 |
Log::Dispatch::Config->configure($config); |
| 267 |
|
| 268 |
CALLER STACK |
| 269 |
When you call logging method from your subroutines / methods, caller |
| 270 |
stack would increase and thus you can't see where the log really comes |
| 271 |
from. |
| 272 |
|
| 273 |
package Logger; |
| 274 |
my $Logger = Log::Dispatch::Config->instance; |
| 275 |
|
| 276 |
sub logit { |
| 277 |
my($class, $level, $msg) = @_; |
| 278 |
$Logger->$level($msg); |
| 279 |
} |
| 280 |
|
| 281 |
package main; |
| 282 |
Logger->logit('debug', 'foobar'); |
| 283 |
|
| 284 |
You can adjust package variable $Log::Dispatch::Config::CallerDepth to |
| 285 |
increase the caller stack depth. The default value is 0. |
| 286 |
|
| 287 |
sub logit { |
| 288 |
my($class, $level, $msg) = @_; |
| 289 |
local $Log::Dispatch::Config::CallerDepth = 1; |
| 290 |
$Logger->$level($msg); |
| 291 |
} |
| 292 |
|
| 293 |
Note that your log caller's namespace should not match against |
| 294 |
"/^Log::Dispatch/", which makes this module confusing. |
| 295 |
|
| 296 |
AUTHOR |
| 297 |
Tatsuhiko Miyagawa <[email protected]> with much help from Matt |
| 298 |
Sergeant <[email protected]>. |
| 299 |
|
| 300 |
This library is free software; you can redistribute it and/or modify it |
| 301 |
under the same terms as Perl itself. |
| 302 |
|
| 303 |
SEE ALSO |
| 304 |
the Log::Dispatch::Configurator::AppConfig manpage, the Log::Dispatch |
| 305 |
manpage, the AppConfig manpage, the POE::Component::Logger manpage |
| 306 |
|