Author: seb Date: Mon Jan 8 16:15:25 2007 New Revision: 1172 Added: logback/trunk/logback-examples/src/main/java/chapter6/basicConfiguration.xml logback/trunk/logback-examples/src/main/java/chapter6/thresholdFilterConfig.xml Modified: logback/trunk/logback-examples/src/main/java/chapter6/FilterEvents.java logback/trunk/logback-examples/src/main/java/chapter6/basicEventEvaluator.xml logback/trunk/logback-site/src/site/xdocTemplates/manual/filters.xml Log: Added filter examples Added/modified doc about LevelFilter and ThresholdFilter Modified: logback/trunk/logback-examples/src/main/java/chapter6/FilterEvents.java ============================================================================== --- logback/trunk/logback-examples/src/main/java/chapter6/FilterEvents.java (original) +++ logback/trunk/logback-examples/src/main/java/chapter6/FilterEvents.java Mon Jan 8 16:15:25 2007 @@ -13,6 +13,11 @@ public class FilterEvents { public static void main(String[] args) throws InterruptedException { + if (args.length == 0) { + System.out.println("A configuration file must be passed as a parameter."); + return; + } + Logger logger = (Logger) LoggerFactory.getLogger(FilterEvents.class); LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory(); @@ -32,12 +37,10 @@ MDC.remove("username"); } else if (i == 6) { Marker billing = MarkerFactory.getMarker("billing"); - logger.error(billing, "logging statement " + i); + logger.error(billing, "billing statement " + i); } else { logger.info("logging statement " + i); } } - - //StatusPrinter.print(lc.getStatusManager()); } } Added: logback/trunk/logback-examples/src/main/java/chapter6/basicConfiguration.xml ============================================================================== --- (empty file) +++ logback/trunk/logback-examples/src/main/java/chapter6/basicConfiguration.xml Mon Jan 8 16:15:25 2007 @@ -0,0 +1,16 @@ +<configuration> + + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern> + %-4relative [%thread] %-5level %logger - %msg%n + </pattern> + </layout> + </appender> + + <root> + <level value="DEBUG" /> + <appender-ref ref="STDOUT" /> + </root> +</configuration> \ No newline at end of file Modified: logback/trunk/logback-examples/src/main/java/chapter6/basicEventEvaluator.xml ============================================================================== --- logback/trunk/logback-examples/src/main/java/chapter6/basicEventEvaluator.xml (original) +++ logback/trunk/logback-examples/src/main/java/chapter6/basicEventEvaluator.xml Mon Jan 8 16:15:25 2007 @@ -1,13 +1,13 @@ -<configuration> +<configuration debug="true"> <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> <filter class="ch.qos.logback.core.filter.EvaluatorFilter"> <evaluator name="myEval"> - <expression>message.contains("important")</expression> + <expression>message.contains("billing")</expression> </evaluator> <OnMismatch>NEUTRAL</OnMismatch> - <OnMatch>ACCEPT</OnMatch> + <OnMatch>DENY</OnMatch> </filter> <layout class="ch.qos.logback.classic.PatternLayout"> <pattern> @@ -17,7 +17,7 @@ </appender> <root> - <level value="INFO" /> + <level value="DEBUG" /> <appender-ref ref="STDOUT" /> </root> </configuration> \ No newline at end of file Added: logback/trunk/logback-examples/src/main/java/chapter6/thresholdFilterConfig.xml ============================================================================== --- (empty file) +++ logback/trunk/logback-examples/src/main/java/chapter6/thresholdFilterConfig.xml Mon Jan 8 16:15:25 2007 @@ -0,0 +1,19 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<configuration> + <appender name="CONSOLE" + class="ch.qos.logback.core.ConsoleAppender"> + <filter class="ch.qos.logback.classic.filter.ThresholdFilter"> + <level>INFO</level> + </filter> + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern> + %-4relative [%thread] %-5level %logger{30} - %msg%n + </pattern> + </layout> + </appender> + <root> + <level value="DEBUG" /> + <appender-ref ref="CONSOLE" /> + </root> +</configuration> \ No newline at end of file Modified: logback/trunk/logback-site/src/site/xdocTemplates/manual/filters.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/manual/filters.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/manual/filters.xml Mon Jan 8 16:15:25 2007 @@ -184,17 +184,16 @@ <h3>Logback Filters</h3> <p> - As the moment, there is one filter that ships with - logback. This is the most commonly used filter: + As the moment, there are two filters that ship with logback. <a href="../xref/ch/qos/logback/classic/LevelFilter.html"> - <code>LevelFilter</code></a>. - It provides event filtering based on a <code>Level</code> value. It the event's - level is equal or higher than the configured level, the filter accepts of denies - the event, depending on its configuration. Here is a sample configuration that + <code>LevelFilter</code></a> provides event filtering based on a <code>Level</code> value. + It the event's level is equal to the configured level, the filter accepts of denies + the event, depending on its configuration. It allows you to choose the + behaviour of logback for a precise given level. Here is a sample configuration that uses <code>LevelFilter</code>. </p> -<em>Example 6.3: SampleFilter configuration (logback-examples/src/main/java/chapter6/LevelFilterConfig.xml)</em> +<em>Example 6.3: Sample LevelFilter configuration (logback-examples/src/main/java/chapter6/LevelFilterConfig.xml)</em> <div class="source"><pre><configuration> <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender"> @@ -215,6 +214,34 @@ </root> </configuration></pre></div> + <p> + The second filter that ships with logback is + <a href="../xref/ch/qos/logback/classic/ThresholdFilter.html"> + <code>ThresholdFilter</code></a>. + It is also based on level value, but acts as a threshold to deny any request + whose level is not equal or greater to the configured level. A sample + use of the <code>ThresholdFilter</code> is shown below. + </p> + +<em>Example 6.4: Sample ThresholdFilter configuration (logback-examples/src/main/java/chapter6/ThresholdFilterConfig.xml)</em> +<div class="source"><pre><configuration> + <appender name="CONSOLE" + class="ch.qos.logback.core.ConsoleAppender"> + <b><filter class="ch.qos.logback.classic.filter.ThresholdFilter"> + <level>INFO</level> + </filter></b> + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern> + %-4relative [%thread] %-5level %logger{30} - %msg%n + </pattern> + </layout> + </appender> + <root> + <level value="DEBUG" /> + <appender-ref ref="CONSOLE" /> + </root> +</configuration></pre></div> + <h3>Evaluator Filters</h3> <p> @@ -247,17 +274,17 @@ Let's see a sample configuration. </p> -<em>Example 6.4: Basic event evaluator usage (logback-examples/src/main/java/chapter6/basicEventEvaluator.xml)</em> +<em>Example 6.5: Basic event evaluator usage (logback-examples/src/main/java/chapter6/basicEventEvaluator.xml)</em> <div class="source"><pre><configuration> <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> <b><filter class="ch.qos.logback.core.filter.EvaluatorFilter"> <evaluator name="myEval"> - <expression>message.contains("important")</expression> + <expression>message.contains("billing")</expression> </evaluator> <OnMismatch>NEUTRAL</OnMismatch> - <OnMatch>ACCEPT</OnMatch> + <OnMatch>DENY</OnMatch> </filter></b> <layout class="ch.qos.logback.classic.PatternLayout"> <pattern> @@ -371,6 +398,68 @@ evaluate this logging event. </p> + <p> + Let us see an example of <code>EvaluatorFilter</code>. The <code>FilterEvents</code> + class issues ten logging requests, numbered from 0 to 9. + </p> + + <p> + First, let us run the <code>FilterEvents</code> class with a configuration that does + not contain any filters. This can be done by issuing the following command: + </p> + +<div class="source"><pre> +java chapter6.FilterEvents src/main/java/chapter6/basicConfiguration.xml +</pre></div> + + <p> + All requests will be displayed, as shown below: + </p> + +<div class="source"><pre>0 [main] INFO chapter6.FilterEvents - logging statement 0 +0 [main] INFO chapter6.FilterEvents - logging statement 1 +0 [main] INFO chapter6.FilterEvents - logging statement 2 +0 [main] DEBUG chapter6.FilterEvents - logging statement 3 +0 [main] INFO chapter6.FilterEvents - logging statement 4 +0 [main] INFO chapter6.FilterEvents - logging statement 5 +0 [main] ERROR chapter6.FilterEvents - <b>billing statement 6</b> +0 [main] INFO chapter6.FilterEvents - logging statement 7 +0 [main] INFO chapter6.FilterEvents - logging statement 8 +0 [main] INFO chapter6.FilterEvents - logging statement 9</pre></div> + + <p> + Suppose that we want to get rid of the billing information. We + can use an <code>EvaluatorFilter</code> configured as follows: + </p> + +<div class="source"><pre><configuration> + ... + <filter class="ch.qos.logback.core.filter.EvaluatorFilter"> + <evaluator name="myEval"> + <expression>message.contains("billing")</expression> + </evaluator> + <OnMismatch>NEUTRAL</OnMismatch> + <OnMatch>DENY</OnMatch> + </filter> + ... +</configuration></pre></div> + + <p> + This filter will deny any logging event whose message + contains the String <em>billing</em>. If we run the <code>FilterEvents</code> + class again, we obtain the following output: + </p> + +<div class="source"><pre>0 [main] INFO chapter6.FilterEvents - logging statement 0 +0 [main] INFO chapter6.FilterEvents - logging statement 1 +0 [main] INFO chapter6.FilterEvents - logging statement 2 +0 [main] DEBUG chapter6.FilterEvents - logging statement 3 +0 [main] INFO chapter6.FilterEvents - logging statement 4 +0 [main] INFO chapter6.FilterEvents - logging statement 5 +0 [main] INFO chapter6.FilterEvents - logging statement 7 +0 [main] INFO chapter6.FilterEvents - logging statement 8 +0 [main] INFO chapter6.FilterEvents - logging statement 9</pre></div> + <a name="TurboFilter" /> <h3>TurboFilters</h3> @@ -412,7 +501,7 @@ create a slightly more complex filter: </p> -<em>Example 6.5: Basic custom <code>TurboFilter</code> (<a href="../xref/chapter6/SampleTurboFilter.html">logback-examples/src/main/java/chapter6/SampleTurboFilter.java</a>)</em> +<em>Example 6.6: Basic custom <code>TurboFilter</code> (<a href="../xref/chapter6/SampleTurboFilter.html">logback-examples/src/main/java/chapter6/SampleTurboFilter.java</a>)</em> <div class="source"><pre>package chapter6; import org.slf4j.Marker; @@ -478,7 +567,7 @@ Here is a sample configuration that makes use of the newly created <code>TurboFilter</code>. </p> -<em>Example 6.6: Basic custom <code>TurboFilter</code> configuration (logback-examples/src/main/java/chapter6/sampleTurboFilterConfig.xml)</em> +<em>Example 6.7: Basic custom <code>TurboFilter</code> configuration (logback-examples/src/main/java/chapter6/sampleTurboFilterConfig.xml)</em> <div class="source"><pre><configuration> <b><turboFilter class="chapter6.SampleTurboFilter"> <Marker>sample</Marker> @@ -512,7 +601,7 @@ <code>MarkerFilter</code>. </p> -<em>Example 6.7: <code>MDCFilter</code> and <code>MarkerFilter</code> +<em>Example 6.8: <code>MDCFilter</code> and <code>MarkerFilter</code> configuration (logback-examples/src/main/java/chapter6/turboFilters.xml)</em> <div class="source"><pre><configuration> @@ -548,7 +637,7 @@ </pre></div> <p> - The <code>FilterEvents</code> class creates 10 logging requests, + As we've seen previously, the <code>FilterEvents</code> class creates 10 logging requests, each with its number from 0 to 9. All of the requests are of level <em>INFO</em>, just like the configured overall level, except for two requests. The 3rd request, is a <em>DEBUG</em> level corresponding to the key <em>username</em>. @@ -618,7 +707,7 @@ Here is a sample configuration that will ensure that any 404 error will be displayed: </p> -<em>Example 6.8: Access Evaluator (logback-examples/src/main/java/chapter6/accessEventEvaluator.xml)</em> +<em>Example 6.9: Access Evaluator (logback-examples/src/main/java/chapter6/accessEventEvaluator.xml)</em> <div class="source"><pre><configuration> <appender name="STDOUT" @@ -646,7 +735,7 @@ would look like: </p> -<em>Example 6.9: Access Evaluator (logback-examples/src/main/java/chapter6/accessEventEvaluator2.xml)</em> +<em>Example 6.10: Access Evaluator (logback-examples/src/main/java/chapter6/accessEventEvaluator2.xml)</em> <div class="source"><pre><configuration> <appender name="STDOUT"