1NAME
2 Log::Dispatch::Config - Log4j for Perl
3
4SYNOPSIS
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
21DESCRIPTION
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
27METHOD
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
46CONFIGURATION
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
140SINGLETON
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
163NAMESPACE 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
179PLUGGABLE 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
268CALLER 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
296AUTHOR
297 Tatsuhiko Miyagawa <miyagawa@bulknews.net> with much help from Matt
298 Sergeant <matt@sergeant.org>.
299
300 This library is free software; you can redistribute it and/or modify it
301 under the same terms as Perl itself.
302
303SEE ALSO
304 the Log::Dispatch::Configurator::AppConfig manpage, the Log::Dispatch
305 manpage, the AppConfig manpage, the POE::Component::Logger manpage
306
307