root/Log-Dispatch-Config/trunk/README

Revision 344 (checked in by miyagawa, 19 years ago)

Initial revision

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1 NAME
2     Log::Dispatch::Config - Log4j for Perl
3
4 SYNOPSIS
5       use Log::Dispatch::Config;
6       Log::Dispatch::Config->configure('/path/to/config');
7
8       my $dispatcher = Log::Dispatch->instance;
9
10 DESCRIPTION
11     Log::Dispatch::Config provides a way to configure Log::Dispatch with
12     configulation file (in AppConfig format). I mean, this is log4j for Perl,
13     not with all API compatibility though.
14
15 METHOD
16     This module has one class method `configure' which parses config file and
17     declares `instance' method in Log::Dispatch namespace. So what you should
18     do is call `configure' method once in somewhere (like `startup.pl' in
19     mod_perl), then you can get configured dispatcher instance via
20     `Log::Dispatch->instance'.
21
22 CONFIGURATION
23     Here is an example of the config file:
24
25       dispatchers = file screen
26
27       file.class = Log::Dispatch::File
28       file.min_level = debug
29       file.filename = /path/to/log
30       file.mode = append
31       file.format = [%d] [%p] %m at %F line %L%n
32
33       screen.class = Log::Dispatch::Screen
34       screen.min_level = info
35       screen.stderr = 1
36       screen.format = %m
37
38     Config file is parsed with AppConfig module, see the AppConfig manpage
39     when you face configuration parsing error.
40
41   GLOBAL PARAMETERS
42
43     dispatchers
44           dispatchers = file screen
45
46         `dispatchers' defines logger names, which will be splitted by spaces.
47         If this parameter is unset, no logging is done.
48
49     format
50           format = [%d] [%p] %m at %F line %L%n
51           format = [${datetime}] [${prioity}] ${message} at ${filename} line ${line}\n
52
53         `format' defines log format. `%X' style and `${XXX}' style are both
54         supported. Possible conversions format are
55
56           %d ${datetime}        datetime string
57           %p ${priority}        priority (debug, indo, warn ...)
58           %m ${message}         message string
59           %F ${filename}        filename
60           %L ${line}            line number
61           %P ${package}         package
62           %n                    newline (\n)
63
64         `format' defined here would apply to all the log messages to
65         dispatchers. This parameter is optional.
66
67   PARAMETERS FOR EACH DISPATCHER
68
69     Parameters for each dispatcher should be prefixed with "name.", where
70     "name" is the name of each one, defined in global `dispatchers' parameter.
71
72     class
73           screen.class = Log::Dispatch::Screen
74
75         `class' defines class name of Log::Dispatch subclasses. This parameter
76         is essential.
77
78     format
79           screen.format = -- %m --
80
81         `format' defines log format which would be applied only to the
82         dispatcher. Note that if you define global `format' also, `%m' is
83         double formated (first global one, next each dispatcher one). This
84         parameter is optional.
85
86     (others)
87           screen.min_level = info
88           screen.stderr = 1
89
90         Other parameters would be passed to the each dispatcher construction.
91         See Log::Dispatch::* manpage for the details.
92
93 SINGLETON
94     Declared `instance' method would make `Log::Dispatch' class singleton, so
95     multiple calls of `instance' will all result in returning same object.
96
97       my $one = Log::Dispatch->instance;
98       my $two = Log::Dispatch->instance; # same as $one
99
100     See GoF Design Pattern book for Singleton Pattern.
101
102     But in practice, in persistent environment like mod_perl, Singleton
103     instance is not so useful. Log::Dispatch::Config defines `instance' method
104     so that the object reloads itself when configuration file is modified
105     since its last object creation time.
106
107 TODO
108     *   LogLevel configuration depending on caller package like log4j?
109
110 AUTHOR
111     Tatsuhiko Miyagawa <miyagawa@bulknews.net>
112
113     This library is free software; you can redistribute it and/or modify it
114     under the same terms as Perl itself.
115
116 SEE ALSO
117     the Log::Dispatch manpage, the AppConfig manpage
118
Note: See TracBrowser for help on using the browser.