Log::Dispatch::Config(3pm)

1Log::Dispatch::Config(3U)ser Contributed Perl DocumentatiLoong::Dispatch::Config(3)
2
3
4

NAME

6       Log::Dispatch::Config - Log4j for Perl
7

SYNOPSIS

9         use Log::Dispatch::Config;
10         Log::Dispatch::Config->configure('/path/to/log.conf');
11
12         my $dispatcher = Log::Dispatch::Config->instance;
13         $dispatcher->debug('this is debug message');
14         $dispatcher->emergency('something *bad* happened!');
15
16         # automatic reloading conf file, when modified
17         Log::Dispatch::Config->configure_and_watch('/path/to/log.conf');
18
19         # or if you write your own config parser:
20         use Log::Dispatch::Configurator::XMLSimple;
21
22         my $config = Log::Dispatch::Configurator::XMLSimple->new('log.xml');
23         Log::Dispatch::Config->configure($config);
24

DESCRIPTION

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

METHOD

32       This module has a class method "configure" which parses config file for
33       later creation of the Log::Dispatch::Config singleton instance.
34       (Actual construction of the object is done in the first "instance"
35       call).
36
37       So, what you should do is call "configure" method once in somewhere
38       (like "startup.pl" in mod_perl), then you can get configured dispatcher
39       instance via "Log::Dispatch::Config->instance".
40

CONFIGURATION

42       Here is an example of the config file:
43
44         dispatchers = file screen
45
46         file.class = Log::Dispatch::File
47         file.min_level = debug
48         file.filename = /path/to/log
49         file.mode = append
50         file.format = [%d] [%p] %m at %F line %L%n
51
52         screen.class = Log::Dispatch::Screen
53         screen.min_level = info
54         screen.stderr = 1
55         screen.format = %m
56
57       In this example, config file is written in AppConfig format. See
58       Log::Dispatch::Configurator::AppConfig for details.
59
60       See "PLUGGABLE CONFIGURATOR" for other config parsing scheme.
61
62       GLOBAL PARAMETERS
63
64       dispatchers
65             dispatchers = file screen
66
67           "dispatchers" defines logger names, which will be splitted by spa‐
68           ces.  If this parameter is unset, no logging is done.
69
70       format
71             format = [%d] [%p] %m at %F line %L%n
72
73           "format" defines log format. Possible conversions format are
74
75             %d    datetime string (ctime(3))
76             %p    priority (debug, info, warning ...)
77             %m    message string
78             %F    filename
79             %L    line number
80             %P    package
81             %n    newline (\n)
82             %%    % itself
83
84           Note that datetime (%d) format is configurable by passing "strf‐
85           time" fmt in braket after %d. (I know it looks quite messy, but its
86           compatible with Java Log4j ;)
87
88             format = [%d{%Y%m%d}] %m  # datetime is now strftime "%Y%m%d"
89
90           If you have Time::Piece, this module uses its "strftime" implemen‐
91           tation, otherwise POSIX.
92
93           "format" defined here would apply to all the log messages to dis‐
94           patchers. This parameter is optional.
95
96           See "CALLER STACK" for details about package, line number and file‐
97           name.
98
99       PARAMETERS FOR EACH DISPATCHER
100
101       Parameters for each dispatcher should be prefixed with "name.", where
102       "name" is the name of each one, defined in global "dispatchers" parame‐
103       ter.
104
105       You can also use ".ini" style grouping like:
106
107         [foo]
108         class = Log::Dispatch::File
109         min_level = debug
110
111       See Log::Dispatch::Configurator::AppConfig for details.
112
113       class
114             screen.class = Log::Dispatch::Screen
115
116           "class" defines class name of Log::Dispatch subclasses. This param‐
117           eter is essential.
118
119       format
120             screen.format = -- %m --
121
122           "format" defines log format which would be applied only to the dis‐
123           patcher. Note that if you define global "format" also, %m is double
124           formated (first global one, next each dispatcher one). This parame‐
125           ter is optional.
126
127       (others)
128             screen.min_level = info
129             screen.stderr = 1
130
131           Other parameters would be passed to the each dispatcher construc‐
132           tion. See Log::Dispatch::* manpage for the details.
133

SINGLETON

135       Declared "instance" method would make "Log::Dispatch::Config" class
136       singleton, so multiple calls of "instance" will all result in returning
137       same object.
138
139         my $one = Log::Dispatch::Config->instance;
140         my $two = Log::Dispatch::Config->instance; # same as $one
141
142       See GoF Design Pattern book for Singleton Pattern.
143
144       But in practice, in persistent environment like mod_perl, lifetime of
145       Singleton instance becomes sometimes messy. If you want to reload sin‐
146       gleton object manually, call "reload" method.
147
148         Log::Dispatch::Config->reload;
149
150       And, if you want to reload object on the fly, as you edit "log.conf" or
151       something like that, what you should do is to call "config‐
152       ure_and_watch" method on Log::Dispatch::Config instead of "configure".
153       Then "instance" call will check mtime of configuration file, and com‐
154       pares it with instanciation time of singleton object. If config file is
155       newer than last instanciation, it will automatically reload object.
156

NAMESPACE COLLISION

158       If you use Log::Dispatch::Config in multiple projects on the same perl
159       interpreter (like mod_perl), namespace collision would be a problem.
160       Bizzare thing will happen when you call "Log::Dispatch::Config->config‐
161       ure" multiple times with differenct argument.
162
163       In such cases, what you should do is to define your own logger class.
164
165         package My::Logger;
166         use Log::Dispatch::Config;
167         use base qw(Log::Dispatch::Config);
168
169       Or make wrapper for it. See POE::Component::Logger implementation by
170       Matt Sergeant.
171

PLUGGABLE CONFIGURATOR

173       If you pass filename to "configure" method call, this module handles
174       the config file with AppConfig. You can change config parsing scheme by
175       passing another pluggable configurator object.
176
177       Here is a way to declare new configurator class. The example below is
178       hardwired version equivalent to the one above in "CONFIGURATION".
179
180       ·   Inherit from Log::Dispatch::Configurator.
181
182             package Log::Dispatch::Configurator::Hardwired;
183             use base qw(Log::Dispatch::Configurator);
184
185           Declare your own "new" constructor. Stub "new" method is defined in
186           Configurator base class, but you want to put parsing method in your
187           own constructor. In this example, we just bless reference. Note
188           that your object should be blessed hash.
189
190             sub new { bless {}, shift }
191
192       ·   Implement two required object methods "get_attrs_global" and
193           "get_attrs".
194
195           "get_attrs_global" should return hash reference of global parame‐
196           ters.  "dispatchers" should be an array reference of names of dis‐
197           patchers.
198
199             sub get_attrs_global {
200                 my $self = shift;
201                 return {
202                     format => undef,
203                     dispatchers => [ qw(file screen) ],
204                 };
205             }
206
207           "get_attrs" accepts name of a dispatcher and should return hash
208           reference of parameters associated with the dispatcher.
209
210             sub get_attrs {
211                 my($self, $name) = @_;
212                 if ($name eq 'file') {
213                     return {
214                         class     => 'Log::Dispatch::File',
215                         min_level => 'debug',
216                         filename  => '/path/to/log',
217                         mode      => 'append',
218                         format  => '[%d] [%p] %m at %F line %L%n',
219                     };
220                 }
221                 elsif ($name eq 'screen') {
222                     return {
223                         class     => 'Log::Dispatch::Screen',
224                         min_level => 'info',
225                         stderr    => 1,
226                         format  => '%m',
227                     };
228                 }
229                 else {
230                     die "invalid dispatcher name: $name";
231                 }
232             }
233
234       ·   Implement optional "needs_reload" and "reload" methods.
235           "needs_reload" should return boolean value if the object is stale
236           and needs reloading itself. This method will be triggered when you
237           configure logging object with "configure_and_watch" method.
238
239           Stub config file mtime based "needs_reload" method is declared in
240           Log::Dispatch::Configurator, so if your config class is based on
241           filesystem files, you do not need to reimplement this.
242
243           If you do not need singleton-ness at all, always return true.
244
245             sub needs_reload { 1 }
246
247           "reload" method should redo parsing of the config file. Configura‐
248           tor base class has a stub null "reload" method, so you should bet‐
249           ter override it.
250
251           See Log::Dispatch::Configurator::AppConfig source code for details.
252
253       ·   That's all. Now you can plug your own configurator (Hardwired) into
254           Log::Dispatch::Config. What you should do is to pass configurator
255           object to "configure" method call instead of config file name.
256
257             use Log::Dispatch::Config;
258             use Log::Dispatch::Configurator::Hardwired;
259
260             my $config = Log::Dispatch::Configurator::Hardwired->new;
261             Log::Dispatch::Config->configure($config);
262

CALLER STACK

264       When you call logging method from your subroutines / methods, caller
265       stack would increase and thus you can't see where the log really comes
266       from.
267
268         package Logger;
269         my $Logger = Log::Dispatch::Config->instance;
270
271         sub logit {
272             my($class, $level, $msg) = @_;
273             $Logger->$level($msg);
274         }
275
276         package main;
277         Logger->logit('debug', 'foobar');
278
279       You can adjust package variable $Log::Dispatch::Config::CallerDepth to
280       increase the caller stack depth. The default value is 0.
281
282         sub logit {
283             my($class, $level, $msg) = @_;
284             local $Log::Dispatch::Config::CallerDepth = 1;
285             $Logger->$level($msg);
286         }
287
288       Note that your log caller's namespace should not match against
289       "/^Log::Dispatch/", which makes this module confusing.
290

AUTHOR

292       Tatsuhiko Miyagawa <miyagawa@bulknews.net> with much help from Matt
293       Sergeant <matt@sergeant.org>.
294
295       This library is free software; you can redistribute it and/or modify it
296       under the same terms as Perl itself.
297