1Filter(3) User Contributed Perl Documentation Filter(3)
2
6 Log::Log4perl::Filter - Log4perl Custom Filter Base Class
7
9 use Log::Log4perl;
10 Log::Log4perl->init(\ <<'EOT');
12 log4perl.logger = INFO, Screen
13 log4perl.filter.MyFilter = sub { /let this through/ }
14 log4perl.appender.Screen = Log::Log4perl::Appender::Screen
15 log4perl.appender.Screen.Filter = MyFilter
16 log4perl.appender.Screen.layout = Log::Log4perl::Layout::SimpleLayout
17 EOT
18 # Define a logger
20 my $logger = Log::Log4perl->get_logger("Some");
21 # Let this through
23 $logger->info("Here's the info, let this through!");
24 # Suppress this
26 $logger->info("Here's the info, suppress this!");
27 #################################################################
29 # StringMatch Filter:
30 #################################################################
31 log4perl.filter.M1 = Log::Log4perl::Filter::StringMatch
32 log4perl.filter.M1.StringToMatch = let this through
33 log4perl.filter.M1.AcceptOnMatch = true
34 #################################################################
36 # LevelMatch Filter:
37 #################################################################
38 log4perl.filter.M1 = Log::Log4perl::Filter::LevelMatch
39 log4perl.filter.M1.LevelToMatch = INFO
40 log4perl.filter.M1.AcceptOnMatch = true
41
43 Log4perl allows the use of customized filters in its appenders to
44 control the output of messages. These filters might grep for certain
45 text chunks in a message, verify that its priority matches or exceeds a
46 certain level or that this is the 10th time the same message has been
47 submitted -- and come to a log/no log decision based upon these
48 circumstantial facts.
49 Filters have names and can be specified in two different ways in the
51 Log4perl configuration file: As subroutines or as filter classes.
52 Here's a simple filter named "MyFilter" which just verifies that the
53 oncoming message matches the regular expression "/let this through/i":
54 log4perl.filter.MyFilter = sub { /let this through/i }
56 It exploits the fact that when the subroutine defined above is called
58 on a message, Perl's special $_ variable will be set to the message
59 text (prerendered, i.e. concatenated but not layouted) to be logged.
60 The subroutine is expected to return a true value if it wants the
61 message to be logged or a false value if doesn't.
62 Also, Log::Log4perl will pass a hash to the subroutine, containing all
64 key/value pairs that it would pass to the corresponding appender, as
65 specified in Log::Log4perl::Appender. Here's an example of a filter
66 checking the priority of the oncoming message:
67 log4perl.filter.MyFilter = sub { \
69 my %p = @_; \
70 if($p{log4p_level} eq "WARN" or \
71 $p{log4p_level} eq "INFO") { \
72 return 1; \
73 } \
74 return 0; \
75 }
76 If the message priority equals "WARN" or "INFO", it returns a true
78 value, causing the message to be logged.
79 Predefined Filters
81 For common tasks like verifying that the message priority matches a
82 certain priority, there's already a set of predefined filters
83 available. To perform an exact level match, it's much cleaner to use
84 Log4perl's "LevelMatch" filter instead:
85 log4perl.filter.M1 = Log::Log4perl::Filter::LevelMatch
87 log4perl.filter.M1.LevelToMatch = INFO
88 log4perl.filter.M1.AcceptOnMatch = true
89 This will let the message through if its priority is INFO and suppress
91 it otherwise. The statement can be negated by saying
92 log4perl.filter.M1.AcceptOnMatch = false
94 instead. This way, the message will be logged if its priority is
96 anything but INFO.
97 On a similar note, Log4perl's "StringMatch" filter will check the
99 oncoming message for strings or regular expressions:
100 log4perl.filter.M1 = Log::Log4perl::Filter::StringMatch
102 log4perl.filter.M1.StringToMatch = bl.. bl..
103 log4perl.filter.M1.AcceptOnMatch = true
104 This will open the gate for messages like "blah blah" because the
106 regular expression in the "StringToMatch" matches them. Again, the
107 setting of "AcceptOnMatch" determines if the filter is defined in a
108 positive or negative way.
109 All class filter entries in the configuration file have to adhere to
111 the following rule: Only after a filter has been defined by name and
112 class/subroutine, its attribute values can be assigned, just like the
113 "true" value above gets assigned to the "AcceptOnMatch" attribute after
114 the filter "M1" has been defined.
115 Attaching a filter to an appender
117 Attaching a filter to an appender is as easy as assigning its name to
118 the appender's "Filter" attribute:
119 log4perl.appender.MyAppender.Filter = MyFilter
121 This will cause "Log::Log4perl" to call the filter subroutine/method
123 every time a message is supposed to be passed to the appender.
124 Depending on the filter's return value, "Log::Log4perl" will either
125 continue as planned or withdraw immediately.
126 Combining filters with Log::Log4perl::Filter::Boolean
128 Sometimes, it's useful to combine the output of various filters to
129 arrive at a log/no log decision. While Log4j, Log4perl's mother ship,
130 has chosen to implement this feature as a filter chain, similar to
131 Linux' IP chains, Log4perl tries a different approach.
132 Typically, filter results will not need to be bumped along chains but
134 combined in a programmatic manner using boolean logic. "Log if this
135 filter says 'yes' and that filter says 'no'" is a fairly common
136 requirement, but hard to implement as a chain.
137 "Log::Log4perl::Filter::Boolean" is a specially predefined custom
139 filter for Log4perl. It combines the results of other custom filters in
140 arbitrary ways, using boolean expressions:
141 log4perl.logger = WARN, AppWarn, AppError
143 log4perl.filter.Match1 = sub { /let this through/ }
145 log4perl.filter.Match2 = sub { /and that, too/ }
146 log4perl.filter.MyBoolean = Log::Log4perl::Filter::Boolean
147 log4perl.filter.MyBoolean.logic = Match1 || Match2
148 log4perl.appender.Screen = Log::Log4perl::Appender::Screen
150 log4perl.appender.Screen.Filter = MyBoolean
151 log4perl.appender.Screen.layout = Log::Log4perl::Layout::SimpleLayout
152 "Log::Log4perl::Filter::Boolean"'s boolean expressions allow for
154 combining different appenders by name using AND (&& or &), OR (|| or |)
155 and NOT (!) as logical expressions. Also, parentheses can be used for
156 defining precedences. Operator precedence follows standard Perl
157 conventions. Here's a bunch of examples:
158 Match1 && !Match2 # Match1 and not Match2
160 !(Match1 || Match2) # Neither Match1 nor Match2
161 (Match1 && Match2) || Match3 # Both Match1 and Match2 or Match3
162 Writing your own filter classes
164 If none of Log::Log4perl's predefined filter classes fits your needs,
165 you can easily roll your own: Just define a new class, derive it from
166 the baseclass "Log::Log4perl::Filter", and define its "new" and "ok"
167 methods like this:
168 package Log::Log4perl::Filter::MyFilter;
170 use base Log::Log4perl::Filter;
172 sub new {
174 my ($class, %options) = @_;
175 my $self = { %options,
177 };
178 bless $self, $class;
180 return $self;
182 }
183 sub ok {
185 my ($self, %p) = @_;
186 # ... decide and return 1 or 0
188 }
189 1;
191 Log4perl will call the ok() method to determine if the filter should
193 let the message pass or not. A true return value indicates the message
194 will be logged by the appender, a false value blocks it.
195 Values you've defined for its attributes in Log4perl's configuration
197 file, will be received through its "new" method:
198 log4perl.filter.MyFilter = Log::Log4perl::Filter::MyFilter
200 log4perl.filter.MyFilter.color = red
201 will cause "Log::Log4perl::Filter::MyFilter"'s constructor to be called
203 like this:
204 Log::Log4perl::Filter::MyFilter->new( name => "MyFilter",
206 color => "red" );
207 The custom filter class should use this to set the object's attributes,
209 to have them available later to base log/nolog decisions on it.
210 "ok()" is the filter's method to tell if it agrees or disagrees with
212 logging the message. It will be called by Log::Log4perl whenever it
213 needs the filter to decide. A false value returned by "ok()" will block
214 messages, a true value will let them through.
215 A Practical Example: Level Matching
217 See Log::Log4perl::FAQ for this.
218
220 Log::Log4perl::Filter::LevelMatch, Log::Log4perl::Filter::LevelRange,
221 Log::Log4perl::Filter::StringRange, Log::Log4perl::Filter::Boolean
222
224 Copyright 2002-2013 by Mike Schilli <m@perlmeister.com> and Kevin Goess
225 <cpan@goess.org>.
226 This library is free software; you can redistribute it and/or modify it
228 under the same terms as Perl itself.
229
231 Please contribute patches to the project on Github:
232 http://github.com/mschilli/log4perl
234 Send bug reports or requests for enhancements to the authors via our
236 MAILING LIST (questions, bug reports, suggestions/patches):
238 log4perl-devel@lists.sourceforge.net
239 Authors (please contact them via the list above, not directly): Mike
241 Schilli <m@perlmeister.com>, Kevin Goess <cpan@goess.org>
242 Contributors (in alphabetical order): Ateeq Altaf, Cory Bennett, Jens
244 Berthold, Jeremy Bopp, Hutton Davidson, Chris R. Donnelly, Matisse
245 Enzer, Hugh Esco, Anthony Foiani, James FitzGibbon, Carl Franks, Dennis
246 Gregorovic, Andy Grundman, Paul Harrington, Alexander Hartmaier David
247 Hull, Robert Jacobson, Jason Kohles, Jeff Macdonald, Markus Peter,
248 Brett Rann, Peter Rabbitson, Erik Selberg, Aaron Straup Cope, Lars
249 Thegler, David Viner, Mac Yang.
250perl v5.34.0 2021-07-22 Filter(3)