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       dispatchers
64             dispatchers = file screen
65
66           "dispatchers" defines logger names, which will be splitted by
67           spaces.  If this parameter is unset, no logging is done.
68
69       format
70             format = [%d] [%p] %m at %F line %L%n
71
72           "format" defines log format. Possible conversions format are
73
74             %d    datetime string (ctime(3))
75             %p    priority (debug, info, warning ...)
76             %m    message string
77             %F    filename
78             %L    line number
79             %P    package
80             %n    newline (\n)
81             %%    % itself
82
83           Note that datetime (%d) format is configurable by passing
84           "strftime" fmt in braket after %d. (I know it looks quite messy,
85           but its compatible with Java Log4j ;)
86
87             format = [%d{%Y%m%d}] %m  # datetime is now strftime "%Y%m%d"
88
89           If you have Time::Piece, this module uses its "strftime"
90           implementation, otherwise POSIX.
91
92           "format" defined here would apply to all the log messages to
93           dispatchers. This parameter is optional.
94
95           See "CALLER STACK" for details about package, line number and
96           filename.
97
98   PARAMETERS FOR EACH DISPATCHER
99       Parameters for each dispatcher should be prefixed with "name.", where
100       "name" is the name of each one, defined in global "dispatchers"
101       parameter.
102
103       You can also use ".ini" style grouping like:
104
105         [foo]
106         class = Log::Dispatch::File
107         min_level = debug
108
109       See Log::Dispatch::Configurator::AppConfig for details.
110
111       class
112             screen.class = Log::Dispatch::Screen
113
114           "class" defines class name of Log::Dispatch subclasses. This
115           parameter is essential.
116
117       format
118             screen.format = -- %m --
119
120           "format" defines log format which would be applied only to the
121           dispatcher. Note that if you define global "format" also, %m is
122           double formated (first global one, next each dispatcher one). This
123           parameter is optional.
124
125       (others)
126             screen.min_level = info
127             screen.stderr = 1
128
129           Other parameters would be passed to the each dispatcher
130           construction. See Log::Dispatch::* manpage for the details.
131

SINGLETON

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

NAMESPACE COLLISION

157       If you use Log::Dispatch::Config in multiple projects on the same perl
158       interpreter (like mod_perl), namespace collision would be a problem.
159       Bizzare thing will happen when you call
160       "Log::Dispatch::Config->configure" multiple times with differenct
161       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
196           parameters.  "dispatchers" should be an array reference of names of
197           dispatchers.
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.
248           Configurator base class has a stub null "reload" method, so you
249           should better 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