Author: seb Date: Wed Dec 20 14:54:44 2006 New Revision: 1137 Modified: logback/trunk/logback-examples/src/main/java/chapter6/SampleTurboFilter.java logback/trunk/logback-site/src/site/xdocTemplates/manual/filters.xml logback/trunk/logback-site/src/site/xdocTemplates/manual/mdc.xml Log: corrections to the MDC and Filter chapters Modified: logback/trunk/logback-examples/src/main/java/chapter6/SampleTurboFilter.java ============================================================================== --- logback/trunk/logback-examples/src/main/java/chapter6/SampleTurboFilter.java (original) +++ logback/trunk/logback-examples/src/main/java/chapter6/SampleTurboFilter.java Wed Dec 20 14:54:44 2006 @@ -11,13 +11,17 @@ public class SampleTurboFilter extends TurboFilter { String marker; - Marker acceptedMarker; + Marker markerToAccept; @Override public FilterReply decide(Marker marker, Logger logger, Level level, String format, Object[] params, Throwable t) { + + if (!isStarted()) { + return FilterReply.NEUTRAL; + } - if ((acceptedMarker.equals(marker))) { + if ((markerToAccept.equals(marker))) { return FilterReply.ACCEPT; } else { return FilterReply.NEUTRAL; @@ -35,7 +39,7 @@ @Override public void start() { if (marker != null && marker.trim().length() > 0) { - acceptedMarker = MarkerFactory.getMarker(marker); + markerToAccept = MarkerFactory.getMarker(marker); super.start(); } } 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 Wed Dec 20 14:54:44 2006 @@ -89,22 +89,96 @@ </p> <p> - In logback, <code>Filter</code> objects can only be added to <code>Appender</code> + In logback-classic, <code>Filter</code> objects can only be added to <code>Appender</code> instances. By adding filters to an appender you can filter events by various criteria, such as the contents of the log message, the contents of the MDC, the time of day or any other part of the logging event. </p> - <p> - The criteria can be specified using an expression evaluator. The + <h3>Implementing your own Filter</h3> + + <p> + Creating your own filter is not difficult. All you have to do is extend the <code>Filter</code> + abstract class. The only method that you will have to implement is the <code>decide()</code> + method, allowing you to contentrate only on the behaviour of your filter. + </p> + + <p> + The next class is all it takes to implement one's own filter. All it does is accept + logging events who's message contains the String <em>sample</em>. The filter will give a + neutral response to any logging event who's message does not contain this String. + </p> + +<em>Example 6.2: Basic custom filter (<a href="../xref/chapter6/SampleFilter.html">logback-examples/src/main/java/chapter6/SampleFilter.java</a>)</em> +<div class="source"><pre>package chapter6; + +import ch.qos.logback.classic.spi.LoggingEvent; +import ch.qos.logback.core.filter.Filter; +import ch.qos.logback.core.spi.FilterReply; + +public class SampleFilter extends Filter { + + @Override + public FilterReply decide(Object eventObject) { + LoggingEvent event = (LoggingEvent)eventObject; + + if (event.getMessage().contains("sample")) { + return FilterReply.ACCEPT; + } else { + return FilterReply.NEUTRAL; + } + } +}</pre></div> + + <p> + What is shown above might be the simplest filter. Like any filter, it + can be attached to any appender using the <Filter> element, as + shown below: + </p> + +<em>Example 6.3: SampleFilter configuration (logback-examples/src/main/java/chapter6/SampleFilterConfig.xml)</em> +<div class="source"><pre><configuration> + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <b><Filter class="chapter6.SampleFilter" /></b> + + <layout class="ch.qos.logback.classic.PatternLayout"> + <pattern> + %-4relative [%thread] %-5level %logger - %msg%n + </pattern> + </layout> + </appender> + + <root> + <appender-ref ref="STDOUT" /> + </root> +</configuration></pre></div> + + <p> + Thanks to Joran, logback's powerful configuration framework, adding + an option to such a filter is very easy. Just add the corresponding + getter and setter methods in the class, and you can specify the + option's value in an xml element, nested within the <em>filter</em> element. + </p> + + <h3>Evaluator Filters</h3> + + <p> + A special category of filters ships with logback. The <a href="../xref/ch/qos/logback/core/filter/EvaluatorFilter.html"> - <code>EvaluatorFilter</code></a> class uses an + <code>EvaluatorFilter</code></a> objects use an <a href="../xref/ch/qos/logback/core/boolex/EventEvaluator.html"> <code>EventEvaluator</code></a> to decide wether to accept or deny the request. This allows unprecedented flexibility in the way that you can affect the logging event's filtering. </p> + <p> + Creating a customized filter that makes use of <code>EventEvaluator</code> objects + works the same way as seen previously, except that one must extend the + <code>EvaluatorFilter</code> class, instead of the <code>Filter</code> class. + </p> + <a name="EventEvaluator" /> <h3>Event Evaluators</h3> @@ -147,13 +221,13 @@ The bold part in the previous configuration adds an <code>EvaluatorFilter</code> to a <code>ConsoleAppender</code>. An <code>EventEvaluator</code> is then given to the filter. The <em>expression</em> element contains a recognizable java expression. - Notice that the <em>message</em> variable is not defined anywhere. Logback provides + Notice that the <em>message</em> variable is defined implicitly. Logback provides access to the internal components of a logging event and lets the user build her expression at will. </p> <p> - The variables available to the <code>EventEvaluator</code> are descripbed below: + The implicit variables available to the <code>EventEvaluator</code> are descripbed below: </p> <table> @@ -166,7 +240,10 @@ <td>event </td> <td><code>LoggingEvent</code></td> - <td>The newly created logging event. + <td>The logging event associated with the logging request. + All of the following variables are also available from the event. For example, + <code>event.getMessage()</code> returns the same String value as the <em>message</em> + variable. </td> </tr> <tr> @@ -183,7 +260,7 @@ <td>This object can be treated like a usual logger. In case the logging event is serialized and sent to a remote machine, the usual logger object is dropped and replaced by a <code>LoggerRemoteView</code> object, which - performs much better over the wire. + performs much better when serialized. </td> </tr> <tr> @@ -233,84 +310,12 @@ The behaviour of the filter is also defined by its <span class="option">OnMatch</span> and <span class="option">OnMismatch</span> options. The configuration specifies thanks to these elements the replies that the <code>EvaluatorFilter</code> must give once its - expression has been evaluated. The example above returns a positive reply when the - message of the logging event contains the String <em>important</em>. If this String is - not found in the message, then the filter lets the next filter evaluate whether this - logging event should be accepted, or rejected. - </p> - - <h3>Implementing your own Filter</h3> - - <p> - Creating your own filter is not difficult. If your filter doesn't need any evaluation - functionnalities, then all you have to do is extend the <code>Filter</code> abstract class. - The only method that you will have to implement is the <code>decide()</code> method, allowing - you to contentrate only on the behaviour of your filter. - </p> - - <p> - The next class is all it takes to implement one's own filter. All it does is accept - logging events who's message contains the String <em>sample</em>. The filter will give a - neutral response to any logging event who's message does not contain this String. + expression has been evaluated. The example above returns the value <code>FilterReply.ACCEPT</code> + when the message of the logging event contains the String <em>important</em>. + If <em>important</em> is not contained in the message, then the filter lets the next filter + evaluate this logging event. </p> -<em>Example 6.2: Basic custom filter (<a href="../xref/chapter6/SampleFilter.html">logback-examples/src/main/java/chapter6/SampleFilter.java</a>)</em> -<div class="source"><pre>package chapter6; - -import ch.qos.logback.classic.spi.LoggingEvent; -import ch.qos.logback.core.filter.Filter; -import ch.qos.logback.core.spi.FilterReply; - -public class SampleFilter extends Filter { - - @Override - public FilterReply decide(Object eventObject) { - LoggingEvent event = (LoggingEvent)eventObject; - - if (event.getMessage().contains("sample")) { - return FilterReply.ACCEPT; - } else { - return FilterReply.NEUTRAL; - } - } -}</pre></div> - - <p> - What is shown above might be the simplest filter. Like any filter, it - can be attached to any appender using the <Filter> element, as - shown below: - </p> - -<em>Example 6.3: SampleFilter configuration (logback-examples/src/main/java/chapter6/SampleFilterConfig.xml)</em> -<div class="source"><pre><configuration> - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> - <b><Filter class="chapter6.SampleFilter" /></b> - - <layout class="ch.qos.logback.classic.PatternLayout"> - <pattern> - %-4relative [%thread] %-5level %logger - %msg%n - </pattern> - </layout> - </appender> - - <root> - <appender-ref ref="STDOUT" /> - </root> -</configuration></pre></div> - - <p> - Thanks to Joran, logback's powerful configuration framework, adding - an option to such a filter is very easy. Just add the corresponding - getter and setter methods in the class, and you can specify the - option's value in a xml element, nested in the filter element. - </p> - - <p> - Creating a filter that makes use of <code>EventEvaluator</code> objects - works the same way, except that one must extend the <code>EvaluatorFilter</code> - class, instead of the <code>Filter</code> class. - </p> <a name="TurboFilter" /> <h3>TurboFilters</h3> @@ -335,20 +340,116 @@ </p> <p> - They are called before the <code>LoggingEvent</code> object creation. Their - decision is made based on some of the logging event's components. They require + More importantly, they are called before the <code>LoggingEvent</code> object creation. + Their decision is made based on some of the logging event's components. They require no logging event instanciation, nor any other treatement to provide their filtering functionnalities. They are much more performant than the usual <code>Filter</code> objects. </p> + <h3>Implementing your own TurboFilter</h3> + + <p> + To create your own <code>TurboFilter</code> component, just extend the + <code>TurboFilter</code> abstract class. As previously, when implementing + a custumized filter object, developing a custom <code>TurboFilter</code> only + ask that one implement the <code>decide()</code> method. In the next example, we + 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> +<div class="source"><pre>package chapter6; + +import org.slf4j.Marker; +import org.slf4j.MarkerFactory; + +import ch.qos.logback.classic.Level; +import ch.qos.logback.classic.Logger; +import ch.qos.logback.classic.turbo.TurboFilter; +import ch.qos.logback.core.spi.FilterReply; + +public class SampleTurboFilter extends TurboFilter { + + String marker; + Marker markerToAccept; + + @Override + public FilterReply decide(Marker marker, Logger logger, Level level, + String format, Object[] params, Throwable t) { + + if (!isStarted()) { + return FilterReply.NEUTRAL; + } + + if ((markerToAccept.equals(marker))) { + return FilterReply.ACCEPT; + } else { + return FilterReply.NEUTRAL; + } + } + + public String getMarker() { + return marker; + } + + public void setMarker(String markerStr) { + this.marker = markerStr; + } + + @Override + public void start() { + if (marker != null && marker.trim().length() > 0) { + markerToAccept = MarkerFactory.getMarker(marker); + super.start(); + } + } +} +</pre></div> + + <p> + The <code>TurboFilter</code> above accepts events that contain a specific marker. + If said marker is not found, then the filter passes the responsability to + the next filter in the chain. + </p> + + <p> + To allow more flexibility, the marker that will be tested can be specified + in the configuration file. Hence the getter and setter methods. We also implemented + the <code>start()</code> method, to check that the option has been specified during the + configuration process. + </p> + + <p> + Here is a sample configuration that makes use of the newly created <code>TurboFilter</code>. + </p> + +<em>Example 6.5: 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> + </turboFilter></b> + + <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> + <appender-ref ref="STDOUT" /> + </root> +</configuration></pre></div> + <p> Logback classic ships with several <code>TurboFilter</code> classes ready for use. The <a href="../xref/ch/qos/logback/classic/turbo/MDCFilter.html"><code>MDCFilter</code></a> check the presence of a given value in the MDC. On the other hand, <a href="../xref/ch/qos/logback/classic/turbo/MarkerFilter.html"><code>MarkerFilter</code></a> - checks for the presence of a specific marker attached to the logging request. + checks for the presence of a specific marker associated with the logging request. </p> <p> @@ -397,9 +498,9 @@ 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>. This obviously satisfies the first <code>TurboFilter</code> declared in the previous - configuration file. The 6th request is a <em>ERROR</em> level request, - which is issued along with the <em>billing</em> marker, to match - the requests for the second declared <code>TurboFilter</code>. + configuration file. The 6th request, a <em>ERROR</em> level request, + which is issued along with the <em>billing</em> marker, matches + the second <code>TurboFilter</code>. </p> <p> @@ -432,100 +533,7 @@ Thus, the 6th request was not displayed. </p> - - <h3>Implementing your own TurboFilter</h3> - - <p> - To create your own <code>TurboFilter</code> component, just extend the - <code>TurboFilter</code> abstract class. Like previously, when implementing - a custumized filter object, developing a custom <code>TurboFilter</code> only - ask that one implement the <code>decide()</code> method. In the next example, we - 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> -<div class="source"><pre>package chapter6; - -import org.slf4j.Marker; -import org.slf4j.MarkerFactory; - -import ch.qos.logback.classic.Level; -import ch.qos.logback.classic.Logger; -import ch.qos.logback.classic.turbo.TurboFilter; -import ch.qos.logback.core.spi.FilterReply; - -public class SampleTurboFilter extends TurboFilter { - - String marker; - Marker acceptedMarker; - - @Override - public FilterReply decide(Marker marker, Logger logger, Level level, - String format, Object[] params, Throwable t) { - - if ((acceptedMarker.equals(marker))) { - return FilterReply.ACCEPT; - } else { - return FilterReply.NEUTRAL; - } - } - - public String getMarker() { - return marker; - } - - public void setMarker(String markerStr) { - this.marker = markerStr; - } - - @Override - public void start() { - if (marker != null && marker.trim().length() > 0) { - acceptedMarker = MarkerFactory.getMarker(marker); - super.start(); - } - } -} -</pre></div> - - <p> - The <code>TurboFilter</code> above accepts events that contain a specific marker. - If said marker is not found, then the filter passes the responsability to - the next filter in the chain. - </p> - - <p> - To allow more flexibility, the marker that will be tested can be specified - in the configuration file. Hence the getter and setter methods. We also implemented - the <code>start()</code> method, to check that the option has been specified during the - configuration process. - </p> - - <p> - Here is a sample configuration that makes use of the newly created <code>TurboFilter</code>. - </p> - -<em>Example 6.5: 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> - </turboFilter></b> - - <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> - <appender-ref ref="STDOUT" /> - </root> -</configuration></pre></div> - - + <h2>Logback Access</h2> <p> Modified: logback/trunk/logback-site/src/site/xdocTemplates/manual/mdc.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/manual/mdc.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/manual/mdc.xml Wed Dec 20 14:54:44 2006 @@ -90,7 +90,7 @@ The <code>MDC</code> class contains only static methods. It lets the developer place information in a <em>diagnostic context</em> that can be subsequently retrieved by certain logback components. The - <code>MDC</code> manages contextual information on a per thread basis. + <code>MDC</code> manages contextual information on a <em>per thread basis</em>. Typically, while starting to service a new client request, the developer will insert pertinent contextual information, such as the client id, client's IP address, request parameters etc. into the <code>MDC</code>. Logback components,