1Filter(3)             User Contributed Perl Documentation            Filter(3)
2
3
4

NAME

6       Log::Log4perl::Filter - Log4perl Custom Filter Base Class
7

SYNOPSIS

9         use Log::Log4perl;
10
11         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
19             # Define a logger
20         my $logger = Log::Log4perl->get_logger("Some");
21
22             # Let this through
23         $logger->info("Here's the info, let this through!");
24
25             # Suppress this
26         $logger->info("Here's the info, suppress this!");
27
28         #################################################################
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
35         #################################################################
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

DESCRIPTION

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
50       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
55           log4perl.filter.MyFilter        = sub { /let this through/i }
56
57       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
63       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
68         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
77       If the message priority equals "WARN" or "INFO", it returns a true
78       value, causing the message to be logged.
79
80   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
86         log4perl.filter.M1               = Log::Log4perl::Filter::LevelMatch
87         log4perl.filter.M1.LevelToMatch  = INFO
88         log4perl.filter.M1.AcceptOnMatch = true
89
90       This will let the message through if its priority is INFO and suppress
91       it otherwise. The statement can be negated by saying
92
93         log4perl.filter.M1.AcceptOnMatch = false
94
95       instead. This way, the message will be logged if its priority is
96       anything but INFO.
97
98       On a similar note, Log4perl's "StringMatch" filter will check the
99       oncoming message for strings or regular expressions:
100
101         log4perl.filter.M1               = Log::Log4perl::Filter::StringMatch
102         log4perl.filter.M1.StringToMatch = bl.. bl..
103         log4perl.filter.M1.AcceptOnMatch = true
104
105       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
110       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
116   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
120           log4perl.appender.MyAppender.Filter = MyFilter
121
122       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
127   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
133       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
138       "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
142           log4perl.logger = WARN, AppWarn, AppError
143
144           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
149           log4perl.appender.Screen        = Log::Log4perl::Appender::Screen
150           log4perl.appender.Screen.Filter = MyBoolean
151           log4perl.appender.Screen.layout = Log::Log4perl::Layout::SimpleLayout
152
153       "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
159           Match1 && !Match2            # Match1 and not Match2
160           !(Match1 || Match2)          # Neither Match1 nor Match2
161           (Match1 && Match2) || Match3 # Both Match1 and Match2 or Match3
162
163   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
169           package Log::Log4perl::Filter::MyFilter;
170
171           use base Log::Log4perl::Filter;
172
173           sub new {
174               my ($class, %options) = @_;
175
176               my $self = { %options,
177                          };
178
179               bless $self, $class;
180
181               return $self;
182           }
183
184           sub ok {
185                my ($self, %p) = @_;
186
187                # ... decide and return 1 or 0
188           }
189
190           1;
191
192       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
196       Values you've defined for its attributes in Log4perl's configuration
197       file, will be received through its "new" method:
198
199           log4perl.filter.MyFilter       = Log::Log4perl::Filter::MyFilter
200           log4perl.filter.MyFilter.color = red
201
202       will cause "Log::Log4perl::Filter::MyFilter"'s constructor to be called
203       like this:
204
205           Log::Log4perl::Filter::MyFilter->new( name  => "MyFilter",
206                                                 color => "red" );
207
208       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
211       "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
216   A Practical Example: Level Matching
217       See Log::Log4perl::FAQ for this.
218

SEE ALSO

220       Log::Log4perl::Filter::LevelMatch, Log::Log4perl::Filter::LevelRange,
221       Log::Log4perl::Filter::StringRange, Log::Log4perl::Filter::Boolean
222

LICENSE

224       Copyright 2002-2013 by Mike Schilli <m@perlmeister.com> and Kevin Goess
225       <cpan@goess.org>.
226
227       This library is free software; you can redistribute it and/or modify it
228       under the same terms as Perl itself.
229

AUTHOR

231       Please contribute patches to the project on Github:
232
233           http://github.com/mschilli/log4perl
234
235       Send bug reports or requests for enhancements to the authors via our
236
237       MAILING LIST (questions, bug reports, suggestions/patches):
238       log4perl-devel@lists.sourceforge.net
239
240       Authors (please contact them via the list above, not directly): Mike
241       Schilli <m@perlmeister.com>, Kevin Goess <cpan@goess.org>
242
243       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.
250
251
252
253perl v5.34.0                      2021-07-22                         Filter(3)
Impressum