1Config(3)             User Contributed Perl Documentation            Config(3)
2
3
4

NAME

6       Log::Log4perl::Config - Log4perl configuration file syntax
7

DESCRIPTION

9       In "Log::Log4perl", configuration files are used to describe how the
10       system's loggers ought to behave.
11
12       The format is the same as the one as used for "log4j", just with a few
13       perl-specific extensions, like enabling the "Bar::Twix" syntax instead
14       of insisting on the Java-specific "Bar.Twix".
15
16       Comment lines (starting with arbitrary whitespace and a #) and blank
17       lines (all whitespace or empty) are ignored.
18
19       Also, blanks between syntactical entities are ignored, it doesn't
20       matter if you write
21
22           log4perl.logger.Bar.Twix=WARN,Screen
23
24       or
25
26           log4perl.logger.Bar.Twix = WARN, Screen
27
28       "Log::Log4perl" will strip the blanks while parsing your input.
29
30       Assignments need to be on a single line. However, you can break the
31       line if you want to by using a continuation character at the end of the
32       line. Instead of writing
33
34           log4perl.appender.A1.layout=Log::Log4perl::Layout::SimpleLayout
35
36       you can break the line at any point by putting a backslash at the very
37       (!)  end of the line to be continued:
38
39           log4perl.appender.A1.layout=\
40               Log::Log4perl::Layout::SimpleLayout
41
42       Watch out for trailing blanks after the backslash, which would prevent
43       the line from being properly concatenated.
44
45   Loggers
46       Loggers are addressed by category:
47
48           log4perl.logger.Bar.Twix      = WARN, Screen
49
50       This sets all loggers under the "Bar::Twix" hierarchy on priority
51       "WARN" and attaches a later-to-be-defined "Screen" appender to them.
52       Settings for the root appender (which doesn't have a name) can be
53       accomplished by simply omitting the name:
54
55           log4perl.logger = FATAL, Database, Mailer
56
57       This sets the root appender's level to "FATAL" and also attaches the
58       later-to-be-defined appenders "Database" and "Mailer" to it.
59
60       The additivity flag of a logger is set or cleared via the "additivity"
61       keyword:
62
63           log4perl.additivity.Bar.Twix = 0|1
64
65       (Note the reversed order of keyword and logger name, resulting from the
66       dilemma that a logger name could end in ".additivity" according to the
67       log4j documentation).
68
69   Appenders and Layouts
70       Appender names used in Log4perl configuration file lines need to be
71       resolved later on, in order to define the appender's properties and its
72       layout. To specify properties of an appender, just use the "appender"
73       keyword after the "log4perl" intro and the appender's name:
74
75               # The Bar::Twix logger and its appender
76           log4perl.logger.Bar.Twix = DEBUG, A1
77           log4perl.appender.A1=Log::Log4perl::Appender::File
78           log4perl.appender.A1.filename=test.log
79           log4perl.appender.A1.mode=append
80           log4perl.appender.A1.layout=Log::Log4perl::Layout::SimpleLayout
81
82       This sets a priority of "DEBUG" for loggers in the "Bar::Twix"
83       hierarchy and assigns the "A1" appender to it, which is later on
84       resolved to be an appender of type "Log::Log4perl::Appender::File",
85       simply appending to a log file. According to the
86       "Log::Log4perl::Appender::File" manpage, the "filename" parameter
87       specifies the name of the log file and the "mode" parameter can be set
88       to "append" or "write" (the former will append to the logfile if one
89       with the specified name already exists while the latter would clobber
90       and overwrite it).
91
92       The order of the entries in the configuration file is not important,
93       "Log::Log4perl" will read in the entire file first and try to make
94       sense of the lines after it knows the entire context.
95
96       You can very well define all loggers first and then their appenders
97       (you could even define your appenders first and then your loggers, but
98       let's not go there):
99
100           log4perl.logger.Bar.Twix = DEBUG, A1
101           log4perl.logger.Bar.Snickers = FATAL, A2
102
103           log4perl.appender.A1=Log::Log4perl::Appender::File
104           log4perl.appender.A1.filename=test.log
105           log4perl.appender.A1.mode=append
106           log4perl.appender.A1.layout=Log::Log4perl::Layout::SimpleLayout
107
108           log4perl.appender.A2=Log::Log4perl::Appender::Screen
109           log4perl.appender.A2.stderr=0
110           log4perl.appender.A2.layout=Log::Log4perl::Layout::PatternLayout
111           log4perl.appender.A2.layout.ConversionPattern = %d %m %n
112
113       Note that you have to specify the full path to the layout class and
114       that "ConversionPattern" is the keyword to specify the printf-style
115       formatting instructions.
116

Configuration File Cookbook

118       Here's some examples of often-used Log4perl configuration files:
119
120   Append to STDERR
121           log4perl.category.Bar.Twix      = WARN, Screen
122           log4perl.appender.Screen        = Log::Log4perl::Appender::Screen
123           log4perl.appender.Screen.layout = \
124               Log::Log4perl::Layout::PatternLayout
125           log4perl.appender.Screen.layout.ConversionPattern = %d %m %n
126
127   Append to STDOUT
128           log4perl.category.Bar.Twix      = WARN, Screen
129           log4perl.appender.Screen        = Log::Log4perl::Appender::Screen
130           log4perl.appender.Screen.stderr = 0
131           log4perl.appender.Screen.layout = \
132               Log::Log4perl::Layout::PatternLayout
133           log4perl.appender.Screen.layout.ConversionPattern = %d %m %n
134
135   Append to a log file
136           log4perl.logger.Bar.Twix = DEBUG, A1
137           log4perl.appender.A1=Log::Log4perl::Appender::File
138           log4perl.appender.A1.filename=test.log
139           log4perl.appender.A1.mode=append
140           log4perl.appender.A1.layout = \
141               Log::Log4perl::Layout::PatternLayout
142           log4perl.appender.A1.layout.ConversionPattern = %d %m %n
143
144       Note that you could even leave out
145
146           log4perl.appender.A1.mode=append
147
148       and still have the logger append to the logfile by default, although
149       the "Log::Log4perl::Appender::File" module does exactly the opposite.
150       This is due to some nasty trickery "Log::Log4perl" performs behind the
151       scenes to make sure that beginner's CGI applications don't clobber the
152       log file every time they're called.
153
154   Write a log file from scratch
155       If you loathe the Log::Log4perl's append-by-default strategy, you can
156       certainly override it:
157
158           log4perl.logger.Bar.Twix = DEBUG, A1
159           log4perl.appender.A1=Log::Log4perl::Appender::File
160           log4perl.appender.A1.filename=test.log
161           log4perl.appender.A1.mode=write
162           log4perl.appender.A1.layout=Log::Log4perl::Layout::SimpleLayout
163
164       "write" is the "mode" that has "Log::Log4perl::Appender::File"
165       explicitely clobber the log file if it exists.
166

SEE ALSO

168       Log::Log4perl::Config::PropertyConfigurator
169
170       Log::Log4perl::Config::DOMConfigurator
171
172       Log::Log4perl::Config::LDAPConfigurator (coming soon!)
173

175       Copyright 2002-2009 by Mike Schilli <m@perlmeister.com> and Kevin Goess
176       <cpan@goess.org>.
177
178       This library is free software; you can redistribute it and/or modify it
179       under the same terms as Perl itself.
180
181
182
183perl v5.12.2                      2010-08-31                         Config(3)
Impressum