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 (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 mat‐
20       ter 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
47       Loggers are addressed by category:
48
49           log4perl.logger.Bar.Twix      = WARN, Screen
50
51       This sets all loggers under the "Bar::Twix" hierarchy on priority
52       "WARN" and attaches a later-to-be-defined "Screen" appender to them.
53       Settings for the root appender (which doesn't have a name) can be
54       accomplished by simply omitting the name:
55
56           log4perl.logger = FATAL, Database, Mailer
57
58       This sets the root appender's level to "FATAL" and also attaches the
59       later-to-be-defined appenders "Database" and "Mailer" to it.
60
61       The additivity flag of a logger is set or cleared via the "additivity"
62       keyword:
63
64           log4perl.additivity.Bar.Twix = 0⎪1
65
66       (Note the reversed order of keyword and logger name, resulting from the
67       dilemma that a logger name could end in ".additivity" according to the
68       log4j documentation).
69
70       Appenders and Layouts
71
72       Appender names used in Log4perl configuration file lines need to be
73       resolved later on, in order to define the appender's properties and its
74       layout. To specify properties of an appender, just use the "appender"
75       keyword after the "log4perl" intro and the appender's name:
76
77               # The Bar::Twix logger and its appender
78           log4perl.logger.Bar.Twix = DEBUG, A1
79           log4perl.appender.A1=Log::Log4perl::Appender::File
80           log4perl.appender.A1.filename=test.log
81           log4perl.appender.A1.mode=append
82           log4perl.appender.A1.layout=Log::Log4perl::Layout::SimpleLayout
83
84       This sets a priority of "DEBUG" for loggers in the "Bar::Twix" hierar‐
85       chy and assigns the "A1" appender to it, which is later on resolved to
86       be an appender of type "Log::Log4perl::Appender::File", simply append‐
87       ing to a log file. According to the "Log::Log4perl::Appender::File"
88       manpage, the "filename" parameter specifies the name of the log file
89       and the "mode" parameter can be set to "append" or "write" (the former
90       will append to the logfile if one with the specified name already
91       exists while the latter would clobber and overwrite it).
92
93       The order of the entries in the configuration file is not important,
94       "Log::Log4perl" will read in the entire file first and try to make
95       sense of the lines after it knows the entire context.
96
97       You can very well define all loggers first and then their appenders
98       (you could even define your appenders first and then your loggers, but
99       let's not go there):
100
101           log4perl.logger.Bar.Twix = DEBUG, A1
102           log4perl.logger.Bar.Snickers = FATAL, A2
103
104           log4perl.appender.A1=Log::Log4perl::Appender::File
105           log4perl.appender.A1.filename=test.log
106           log4perl.appender.A1.mode=append
107           log4perl.appender.A1.layout=Log::Log4perl::Layout::SimpleLayout
108
109           log4perl.appender.A2=Log::Log4perl::Appender::Screen
110           log4perl.appender.A2.stderr=0
111           log4perl.appender.A2.layout=Log::Log4perl::Layout::PatternLayout
112           log4perl.appender.A2.layout.ConversionPattern = %d %m %n
113
114       Note that you have to specify the full path to the layout class and
115       that "ConversionPattern" is the keyword to specify the printf-style
116       formatting instructions.
117

Configuration File Cookbook

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

AUTHOR

173       Mike Schilli, <log4perl@perlmeister.com>
174

NAME

DESCRIPTION

Configuration File Cookbook

AUTHOR

SEE ALSO