Log::Log4perl::Config(3pm)

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 and blank lines (all whitespace or empty) are ignored.
17
18       Comment lines may start with arbitrary whitespace followed by one of:
19
20       # - Common comment delimiter
21       ! - Java .properties file comment delimiter accepted by log4j
22       ; - Common .ini file comment delimiter
23
24       Comments at the end of a line are not supported. So if you write
25
26           log4perl.appender.A1.filename=error.log #in current dir
27
28       you will find your messages in a file called "error.log #in current
29       dir".
30
31       Also, blanks between syntactical entities are ignored, it doesn't
32       matter if you write
33
34           log4perl.logger.Bar.Twix=WARN,Screen
35
36       or
37
38           log4perl.logger.Bar.Twix = WARN, Screen
39
40       "Log::Log4perl" will strip the blanks while parsing your input.
41
42       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
46           log4perl.appender.A1.layout=Log::Log4perl::Layout::SimpleLayout
47
48       you can break the line at any point by putting a backslash at the very
49       (!)  end of the line to be continued:
50
51           log4perl.appender.A1.layout=\
52               Log::Log4perl::Layout::SimpleLayout
53
54       Watch out for trailing blanks after the backslash, which would prevent
55       the line from being properly concatenated.
56
57   Loggers
58       Loggers are addressed by category:
59
60           log4perl.logger.Bar.Twix      = WARN, Screen
61
62       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
67           log4perl.logger = FATAL, Database, Mailer
68
69       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
73           log4perl.rootLogger = FATAL, Database, Mailer
74
75       The additivity flag of a logger is set or cleared via the "additivity"
76       keyword:
77
78           log4perl.additivity.Bar.Twix = 0|1
79
80       (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
84   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
90               # 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
97       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
107       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
111       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
115           log4perl.logger.Bar.Twix = DEBUG, A1
116           log4perl.logger.Bar.Snickers = FATAL, A2
117
118           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
123           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
128       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

Configuration File Cookbook

133       Here's some examples of often-used Log4perl configuration files:
134
135   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
142   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
150   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
159       Note that you could even leave out
160
161           log4perl.appender.A1.mode=append
162
163       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
169   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
173           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
179       "write" is the "mode" that has "Log::Log4perl::Appender::File"
180       explicitly clobber the log file if it exists.
181
182   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
187           use Log::Log4perl::Config;
188           Log::Log4perl::Config->utf( 1 );
189
190           Log::Log4perl->init( ... );
191
192       This makes sure Log4perl interprets utf8-encoded config files
193       correctly.  This setting might become the default at some point.
194

LICENSE

203       Copyright 2002-2013 by Mike Schilli <m@perlmeister.com> and Kevin Goess
204       <cpan@goess.org>.
205
206       This library is free software; you can redistribute it and/or modify it
207       under the same terms as Perl itself.
208

AUTHOR

210       Please contribute patches to the project on Github:
211
212           http://github.com/mschilli/log4perl
213
214       Send bug reports or requests for enhancements to the authors via our
215
216       MAILING LIST (questions, bug reports, suggestions/patches):
217       log4perl-devel@lists.sourceforge.net
218
219       Authors (please contact them via the list above, not directly): Mike
220       Schilli <m@perlmeister.com>, Kevin Goess <cpan@goess.org>
221
222       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.
229
230
231
232perl v5.28.0                      2017-02-21                         Config(3)

NAME

DESCRIPTION

Configuration File Cookbook

SEE ALSO

LICENSE

AUTHOR