1Config(3) User Contributed Perl Documentation Config(3)
2
6 Log::Log4perl::Config - Log4perl configuration file syntax
7
9 In "Log::Log4perl", configuration files are used to describe how the
10 system's loggers ought to behave.
11 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 Comment lines and blank lines (all whitespace or empty) are ignored.
17 Comment lines may start with arbitrary whitespace followed by one of:
19 # - Common comment delimiter
21 ! - Java .properties file comment delimiter accepted by log4j
22 ; - Common .ini file comment delimiter
23 Comments at the end of a line are not supported. So if you write
25 log4perl.appender.A1.filename=error.log #in current dir
27 you will find your messages in a file called "error.log #in current
29 dir".
30 Also, blanks between syntactical entities are ignored, it doesn't
32 matter if you write
33 log4perl.logger.Bar.Twix=WARN,Screen
35 or
37 log4perl.logger.Bar.Twix = WARN, Screen
39 "Log::Log4perl" will strip the blanks while parsing your input.
41 Assignments need to be on a single line. However, you can break the
43 line if you want to by using a continuation character at the end of the
44 line. Instead of writing
45 log4perl.appender.A1.layout=Log::Log4perl::Layout::SimpleLayout
47 you can break the line at any point by putting a backslash at the very
49 (!) end of the line to be continued:
50 log4perl.appender.A1.layout=\
52 Log::Log4perl::Layout::SimpleLayout
53 Watch out for trailing blanks after the backslash, which would prevent
55 the line from being properly concatenated.
56 Loggers
58 Loggers are addressed by category:
59 log4perl.logger.Bar.Twix = WARN, Screen
61 This sets all loggers under the "Bar::Twix" hierarchy on priority
63 "WARN" and attaches a later-to-be-defined "Screen" appender to them.
64 Settings for the root appender (which doesn't have a name) can be
65 accomplished by simply omitting the name:
66 log4perl.logger = FATAL, Database, Mailer
68 This sets the root appender's level to "FATAL" and also attaches the
70 later-to-be-defined appenders "Database" and "Mailer" to it.
71 Alternatively, the root logger can be addressed as "rootLogger":
72 log4perl.rootLogger = FATAL, Database, Mailer
74 The additivity flag of a logger is set or cleared via the "additivity"
76 keyword:
77 log4perl.additivity.Bar.Twix = 0|1
79 (Note the reversed order of keyword and logger name, resulting from the
81 dilemma that a logger name could end in ".additivity" according to the
82 log4j documentation).
83 Appenders and Layouts
85 Appender names used in Log4perl configuration file lines need to be
86 resolved later on, in order to define the appender's properties and its
87 layout. To specify properties of an appender, just use the "appender"
88 keyword after the "log4perl" intro and the appender's name:
89 # The Bar::Twix logger and its appender
91 log4perl.logger.Bar.Twix = DEBUG, A1
92 log4perl.appender.A1=Log::Log4perl::Appender::File
93 log4perl.appender.A1.filename=test.log
94 log4perl.appender.A1.mode=append
95 log4perl.appender.A1.layout=Log::Log4perl::Layout::SimpleLayout
96 This sets a priority of "DEBUG" for loggers in the "Bar::Twix"
98 hierarchy and assigns the "A1" appender to it, which is later on
99 resolved to be an appender of type "Log::Log4perl::Appender::File",
100 simply appending to a log file. According to the
101 "Log::Log4perl::Appender::File" manpage, the "filename" parameter
102 specifies the name of the log file and the "mode" parameter can be set
103 to "append" or "write" (the former will append to the logfile if one
104 with the specified name already exists while the latter would clobber
105 and overwrite it).
106 The order of the entries in the configuration file is not important,
108 "Log::Log4perl" will read in the entire file first and try to make
109 sense of the lines after it knows the entire context.
110 You can very well define all loggers first and then their appenders
112 (you could even define your appenders first and then your loggers, but
113 let's not go there):
114 log4perl.logger.Bar.Twix = DEBUG, A1
116 log4perl.logger.Bar.Snickers = FATAL, A2
117 log4perl.appender.A1=Log::Log4perl::Appender::File
119 log4perl.appender.A1.filename=test.log
120 log4perl.appender.A1.mode=append
121 log4perl.appender.A1.layout=Log::Log4perl::Layout::SimpleLayout
122 log4perl.appender.A2=Log::Log4perl::Appender::Screen
124 log4perl.appender.A2.stderr=0
125 log4perl.appender.A2.layout=Log::Log4perl::Layout::PatternLayout
126 log4perl.appender.A2.layout.ConversionPattern = %d %m %n
127 Note that you have to specify the full path to the layout class and
129 that "ConversionPattern" is the keyword to specify the printf-style
130 formatting instructions.
131
133 Here's some examples of often-used Log4perl configuration files:
134 Append to STDERR
136 log4perl.category.Bar.Twix = WARN, Screen
137 log4perl.appender.Screen = Log::Log4perl::Appender::Screen
138 log4perl.appender.Screen.layout = \
139 Log::Log4perl::Layout::PatternLayout
140 log4perl.appender.Screen.layout.ConversionPattern = %d %m %n
141 Append to STDOUT
143 log4perl.category.Bar.Twix = WARN, Screen
144 log4perl.appender.Screen = Log::Log4perl::Appender::Screen
145 log4perl.appender.Screen.stderr = 0
146 log4perl.appender.Screen.layout = \
147 Log::Log4perl::Layout::PatternLayout
148 log4perl.appender.Screen.layout.ConversionPattern = %d %m %n
149 Append to a log file
151 log4perl.logger.Bar.Twix = DEBUG, A1
152 log4perl.appender.A1=Log::Log4perl::Appender::File
153 log4perl.appender.A1.filename=test.log
154 log4perl.appender.A1.mode=append
155 log4perl.appender.A1.layout = \
156 Log::Log4perl::Layout::PatternLayout
157 log4perl.appender.A1.layout.ConversionPattern = %d %m %n
158 Note that you could even leave out
160 log4perl.appender.A1.mode=append
162 and still have the logger append to the logfile by default, although
164 the "Log::Log4perl::Appender::File" module does exactly the opposite.
165 This is due to some nasty trickery "Log::Log4perl" performs behind the
166 scenes to make sure that beginner's CGI applications don't clobber the
167 log file every time they're called.
168 Write a log file from scratch
170 If you loathe the Log::Log4perl's append-by-default strategy, you can
171 certainly override it:
172 log4perl.logger.Bar.Twix = DEBUG, A1
174 log4perl.appender.A1=Log::Log4perl::Appender::File
175 log4perl.appender.A1.filename=test.log
176 log4perl.appender.A1.mode=write
177 log4perl.appender.A1.layout=Log::Log4perl::Layout::SimpleLayout
178 "write" is the "mode" that has "Log::Log4perl::Appender::File"
180 explicitly clobber the log file if it exists.
181 Configuration files encoded in utf-8
183 If your configuration file is encoded in utf-8 (which matters if you
184 e.g. specify utf8-encoded appender filenames in it), then you need to
185 tell Log4perl before running init():
186 use Log::Log4perl::Config;
188 Log::Log4perl::Config->utf( 1 );
189 Log::Log4perl->init( ... );
191 This makes sure Log4perl interprets utf8-encoded config files
193 correctly. This setting might become the default at some point.
194
196 Log::Log4perl::Config::PropertyConfigurator
197 Log::Log4perl::Config::DOMConfigurator
199 Log::Log4perl::Config::LDAPConfigurator (coming soon!)
201
203 Copyright 2002-2013 by Mike Schilli <m@perlmeister.com> and Kevin Goess
204 <cpan@goess.org>.
205 This library is free software; you can redistribute it and/or modify it
207 under the same terms as Perl itself.
208
210 Please contribute patches to the project on Github:
211 http://github.com/mschilli/log4perl
213 Send bug reports or requests for enhancements to the authors via our
215 MAILING LIST (questions, bug reports, suggestions/patches):
217 log4perl-devel@lists.sourceforge.net
218 Authors (please contact them via the list above, not directly): Mike
220 Schilli <m@perlmeister.com>, Kevin Goess <cpan@goess.org>
221 Contributors (in alphabetical order): Ateeq Altaf, Cory Bennett, Jens
223 Berthold, Jeremy Bopp, Hutton Davidson, Chris R. Donnelly, Matisse
224 Enzer, Hugh Esco, Anthony Foiani, James FitzGibbon, Carl Franks, Dennis
225 Gregorovic, Andy Grundman, Paul Harrington, Alexander Hartmaier David
226 Hull, Robert Jacobson, Jason Kohles, Jeff Macdonald, Markus Peter,
227 Brett Rann, Peter Rabbitson, Erik Selberg, Aaron Straup Cope, Lars
228 Thegler, David Viner, Mac Yang.
229perl v5.38.0 2023-07-20 Config(3)