Log::Log4perl::Filter(3pm)

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 con‐
44       trol the output of messages. These filters might grep for certain text
45       chunks in a message, verify that its priority matches or exceeds a cer‐
46       tain level or that this is the 10th time the same message has been sub‐
47       mitted -- and come to a log/no log decision based upon these circum‐
48       stantial 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 "ok()" is called on a message, Perl's
58       special $_ variable will be set to the message text (prerendered, i.e.
59       concatenated but not layouted) to be logged.  The "ok()" subroutine is
60       expected to return a true value if it wants the message to be logged or
61       a false value if doesn't.
62
63       Also, Log::Log4perl will pass a hash to the "ok()" method, containing
64       all key/value pairs that it would pass to the corresponding appender,
65       as 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              $p{log4p_level} eq "WARN" or          \
71              $p{log4p_level} eq "INFO"             \
72                                                 }
73
74       If the message priority equals "WARN" or "INFO", it returns a true
75       value, causing the message to be logged.
76
77       Predefined Filters
78
79       For common tasks like verifying that the message priority matches a
80       certain priority, there's already a set of predefined filters avail‐
81       able. To perform an exact level match, it's much cleaner to use
82       Log4perl's "LevelMatch" filter instead:
83
84         log4perl.filter.M1               = Log::Log4perl::Filter::LevelMatch
85         log4perl.filter.M1.LevelToMatch  = INFO
86         log4perl.filter.M1.AcceptOnMatch = true
87
88       This will let the message through if its priority is INFO and suppress
89       it otherwise. The statement can be negated by saying
90
91         log4perl.filter.M1.AcceptOnMatch = false
92
93       instead. This way, the message will be logged if its priority is any‐
94       thing but INFO.
95
96       On a similar note, Log4perl's "StringMatch" filter will check the
97       oncoming message for strings or regular expressions:
98
99         log4perl.filter.M1               = Log::Log4perl::Filter::StringMatch
100         log4perl.filter.M1.StringToMatch = bl.. bl..
101         log4perl.filter.M1.AcceptOnMatch = true
102
103       This will open the gate for messages like "blah blah" because the regu‐
104       lar expression in the "StringToMatch" matches them. Again, the setting
105       of "AcceptOnMatch" determines if the filter is defined in a positive or
106       negative way.
107
108       All class filter entries in the configuration file have to adhere to
109       the following rule: Only after a filter has been defined by name and
110       class/subroutine, its attribute values can be assigned, just like the
111       "true" value above gets assigned to the "AcceptOnMatch" attribute after
112       the filter "M1" has been defined.
113
114       Attaching a filter to an appender
115
116       Attaching a filter to an appender is as easy as assigning its name to
117       the appender's "Filter" attribute:
118
119           log4perl.appender.MyAppender.Filter = MyFilter
120
121       This will cause "Log::Log4perl" to call the filter subroutine/method
122       every time a message is supposed to be passed to the appender. Depend‐
123       ing on the filter's return value, "Log::Log4perl" will either continue
124       as planned or withdraw immediately.
125
126       Combining filters with Log::Log4perl::Filter::Boolean
127
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 fil‐
139       ter 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 com‐
154       bining 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 con‐
157       ventions. 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
165       If none of Log::Log4perl's predefined filter classes fits your needs,
166       you can easily roll your own: Just define a new class, derive it from
167       the baseclass "Log::Log4perl::Filter", and define its "new" and "ok"
168       methods like this:
169
170           package Log::Log4perl::Filter::MyFilter;
171
172           use base Log::Log4perl::Filter;
173
174           sub new {
175               my ($class, %options) = @_;
176
177               my $self = { %options,
178                          };
179
180               bless $self, $class;
181
182               return $self;
183           }
184
185           sub ok {
186                my ($self, %p) = @_;
187
188                # ... decide and return 1 or 0
189           }
190
191           1;
192
193       Values you've defined for its attributes in Log4perl's configuration
194       file, will be received through its "new" method:
195
196           log4perl.filter.MyFilter       = Log::Log4perl::Filter::MyFilter
197           log4perl.filter.MyFilter.color = red
198
199       will cause "Log::Log4perl::Filter::MyFilter"'s constructor to be called
200       like this:
201
202           Log::Log4perl::Filter::MyFilter->new( name  => "MyFilter",
203                                                 color => "red" );
204
205       The custom filter class should use this to set the object's attributes,
206       to have them available later to base log/nolog decisions on it.
207
208       "ok()" is the filter's method to tell if it agrees or disagrees with
209       logging the message. It will be called by Log::Log4perl whenever it
210       needs the filter to decide. A false value returned by "ok()" will block
211       messages, a true value will let them through.
212
213       A Practical Example: Level Matching
214
215       See Log::Log4perl::FAQ for this.
216

AUTHOR

222       Mike Schilli, <log4perl@perlmeister.com>, 2003
223
224
225
226perl v5.8.8                       2002-07-10                         Filter(3)

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO

AUTHOR