1Appender(3) User Contributed Perl Documentation Appender(3)
2
6 Log::Log4perl::Appender - Log appender class
7
9 use Log::Log4perl;
10 # Define a logger
12 my $logger = Log::Log4perl->get_logger("abc.def.ghi");
13 # Define a layout
15 my $layout = Log::Log4perl::Layout::PatternLayout->new(
16 "%d (%F:%L)> %m");
17 # Define an appender
19 my $appender = Log::Log4perl::Appender->new(
20 "Log::Log4perl::Appender::Screen",
21 name => 'dumpy');
22 # Set the appender's layout
24 $appender->layout($layout);
25 $logger->add_appender($appender);
26
28 This class is a wrapper around the "Log::Log4perl::Appender" appender
29 set.
30 It also supports the <Log::Dispatch::*> collections of appenders. The
32 module hides the idiosyncrasies of "Log::Dispatch" (e.g. every dis‐
33 patcher gotta have a name, but there's no accessor to retrieve it) from
34 "Log::Log4perl" and yet re-uses the extremely useful variety of dis‐
35 patchers already created and tested in "Log::Dispatch".
36
38 Log::Log4perl::Appender->new($dispatcher_class_name, ...);
39 The constructor "new()" takes the name of the appender class to be cre‐
41 ated as a string (!) argument, optionally followed by a number of
42 appender-specific parameters, for example:
43 # Define an appender
45 my $appender = Log::Log4perl::Appender->new(
46 "Log::Log4perl::Appender::File"
47 filename => 'out.log');
48 In case of "Log::Dispatch" appenders, if no "name" parameter is speci‐
50 fied, the appender object will create a unique one (format "appNNN"),
51 which can be retrieved later via the "name()" method:
52 print "The appender's name is ", $appender->name(), "\n";
54 Other parameters are specific to the appender class being used. In the
56 case above, the "filename" parameter specifies the name of the
57 "Log::Log4perl::Appender::File" dispatcher used.
58 However, if, for instance, you're using a "Log::Dispatch::Email" dis‐
60 patcher to send you email, you'll have to specify "from" and "to" email
61 addresses. Every dispatcher is different. Please check the "Log::Dis‐
62 patch::*" documentation for the appender used for details on specific
63 requirements.
64 The "new()" method will just pass these parameters on to a newly cre‐
66 ated "Log::Dispatch::*" object of the specified type.
67 When it comes to logging, the "Log::Log4perl::Appender" will transpar‐
69 ently relay all messages to the "Log::Dispatch::*" object it carries in
70 its womb.
71 $appender->layout($layout);
73 The "layout()" method sets the log layout used by the appender to the
75 format specified by the "Log::Log4perl::Layout::*" object which is
76 passed to it as a reference. Currently there's two layouts available:
77 Log::Log4perl::Layout::SimpleLayout
79 Log::Log4perl::Layout::PatternLayout
80 Please check the Log::Log4perl::Layout::SimpleLayout and
82 Log::Log4perl::Layout::PatternLayout manual pages for details.
83
85 Here's the list of appender modules currently available via "Log::Dis‐
86 patch", if not noted otherwise, written by Dave Rolsky:
87 Log::Dispatch::ApacheLog
89 Log::Dispatch::DBI (by Tatsuhiko Miyagawa)
90 Log::Dispatch::Email,
91 Log::Dispatch::Email::MailSend,
92 Log::Dispatch::Email::MailSendmail,
93 Log::Dispatch::Email::MIMELite
94 Log::Dispatch::File
95 Log::Dispatch::FileRotate (by Mark Pfeiffer)
96 Log::Dispatch::Handle
97 Log::Dispatch::Screen
98 Log::Dispatch::Syslog
99 Log::Dispatch::Tk (by Dominique Dumont)
100 "Log4perl" doesn't care which ones you use, they're all handled in the
102 same way via the "Log::Log4perl::Appender" interface. Please check the
103 well-written manual pages of the "Log::Dispatch" hierarchy on how to
104 use each one of them.
105
107 When calling the appender's log()-Funktion, Log::Log4perl will submit a
108 list of key/value pairs. Entries to the following keys are guaranteed
109 to be present:
110 message
112 Text of the rendered message
113 log4p_category
115 Name of the category of the logger that triggered the event.
116 log4p_level
118 Log::Log4perl level of the event
119
121 Since the "Log::Dispatch::File" appender truncates log files by
122 default, and most of the time this is not what you want, we've
123 instructed "Log::Log4perl" to change this behaviour by slipping it the
124 "mode => append" parameter behind the scenes. So, effectively with
125 "Log::Log4perl" 0.23, a configuration like
126 log4perl.category = INFO, FileAppndr
128 log4perl.appender.FileAppndr = Log::Dispatch::File
129 log4perl.appender.FileAppndr.filename = test.log
130 log4perl.appender.FileAppndr.layout = Log::Log4perl::Layout::SimpleLayout
131 will always append to an existing logfile "test.log" while if you
133 specifically request clobbering like in
134 log4perl.category = INFO, FileAppndr
136 log4perl.appender.FileAppndr = Log::Dispatch::File
137 log4perl.appender.FileAppndr.filename = test.log
138 log4perl.appender.FileAppndr.mode = write
139 log4perl.appender.FileAppndr.layout = Log::Log4perl::Layout::SimpleLayout
140 it will overwrite an existing log file "test.log" and start from
142 scratch.
143
145 Instead of simple strings, certain appenders are expecting multiple
146 fields as log messages. If a statement like
147 $logger->debug($ip, $user, "signed in");
149 causes an off-the-shelf "Log::Log4perl::Screen" appender to fire, the
151 appender will just concatenate the three message chunks passed to it in
152 order to form a single string. The chunks will be separated by a
153 string defined in $Log::Log4perl::JOIN_MSG_ARRAY_CHAR (defaults to the
154 empty string "").
155 However, different appenders might choose to interpret the message
157 above differently: An appender like "Log::Log4perl::Appender::DBI"
158 might take the three arguments passed to the logger and put them in
159 three separate rows into the DB.
160 The "warp_message" appender option is used to specify the desired be‐
162 haviour. If no setting for the appender property
163 # *** Not defined ***
165 # log4perl.appender.SomeApp.warp_message
166 is defined in the Log4perl configuration file, the appender referenced
168 by "SomeApp" will fall back to the standard behaviour and join all mes‐
169 sage chunks together, separating them by
170 $Log::Log4perl::JOIN_MSG_ARRAY_CHAR.
171 If, on the other hand, it is set to a false value, like in
173 log4perl.appender.SomeApp.layout=NoopLayout
175 log4perl.appender.SomeApp.warp_message = 0
176 then the message chunks are passed unmodified to the appender as an
178 array reference. Please note that you need to set the appender's layout
179 to "Log::Log4perl::Layout::NoopLayout" which just leaves the messages
180 chunks alone instead of formatting them or replacing conversion speci‐
181 fiers.
182 Please note that the standard appenders in the Log::Dispatch hierarchy
184 will choke on a bunch of messages passed to them as an array reference.
185 You can't use "warp_message = 0" (or the function name syntax defined
186 below) on them. Only special appenders like Log::Log4perl::Appen‐
187 der::DBI can deal with this.
188 If (and now we're getting fancy) an appender expects message chunks,
190 but we would like to pre-inspect and probably modify them before
191 they're actually passed to the appender's "log" method, an inspection
192 subroutine can be defined with the appender's "warp_message" property:
193 log4perl.appender.SomeApp.layout=NoopLayout
195 log4perl.appender.SomeApp.warp_message = sub { \
196 $#_ = 2 if @_ > 3; \
197 return @_; }
198 The inspection subroutine defined by the "warp_message" property will
200 receive the list of message chunks, like they were passed to the logger
201 and is expected to return a corrected list. The example above simply
202 limits the argument list to a maximum of three by cutting off excess
203 elements and returning the shortened list.
204 Also, the warp function can be specified by name like in
206 log4perl.appender.SomeApp.layout=NoopLayout
208 log4perl.appender.SomeApp.warp_message = main::filter_my_message
209 In this example, "filter_my_message" is a function in the "main" pack‐
211 age, defined like this:
212 my $COUNTER = 0;
214 sub filter_my_message {
216 my @chunks = @_;
217 unshift @chunks, ++$COUNTER;
218 return @chunks;
219 }
220 The subroutine above will add an ever increasing counter as an addi‐
222 tional first field to every message passed to the "SomeApp" appender --
223 but not to any other appender in the system.
224
226 Log::Dispatch
227
229 Mike Schilli, <log4perl@perlmeister.com>
230perl v5.8.8 2002-07-10 Appender(3)