[logback-dev] svn commit: r1061 - in logback/trunk: logback-examples/src/main/java/chapter6 logback-site/src/site/xdocTemplates/manual
noreply.seb at qos.ch
noreply.seb at qos.ch
Mon Dec 4 15:25:04 CET 2006
Author: seb
Date: Mon Dec 4 15:25:04 2006
New Revision: 1061
Added:
logback/trunk/logback-examples/src/main/java/chapter6/FilterEvents.java
logback/trunk/logback-examples/src/main/java/chapter6/turboFilters.xml
Modified:
logback/trunk/logback-site/src/site/xdocTemplates/manual/filters.xml
Log:
more documentation and examples on chapter 6
Added: logback/trunk/logback-examples/src/main/java/chapter6/FilterEvents.java
==============================================================================
--- (empty file)
+++ logback/trunk/logback-examples/src/main/java/chapter6/FilterEvents.java Mon Dec 4 15:25:04 2006
@@ -0,0 +1,43 @@
+package chapter6;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.slf4j.Marker;
+import org.slf4j.MarkerFactory;
+
+import ch.qos.logback.classic.LoggerContext;
+import ch.qos.logback.classic.MDC;
+import ch.qos.logback.classic.joran.JoranConfigurator;
+import ch.qos.logback.core.joran.spi.JoranException;
+
+public class FilterEvents {
+
+ public static void main(String[] args) throws InterruptedException {
+ Logger logger = (Logger) LoggerFactory.getLogger(FilterEvents.class);
+ LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory();
+
+ try {
+ JoranConfigurator configurator = new JoranConfigurator();
+ configurator.setContext(lc);
+ lc.shutdownAndReset();
+ configurator.doConfigure(args[0]);
+ } catch (JoranException je) {
+ je.printStackTrace();
+ }
+
+ for (int i = 0; i < 10; i++) {
+ if (i == 3) {
+ MDC.put("username", "sebastien");
+ logger.debug("logging statement " + i);
+ MDC.remove("username");
+ } else if (i == 6) {
+ Marker billing = MarkerFactory.getMarker("billing");
+ logger.error(billing, "logging statement " + i);
+ } else {
+ logger.info("logging statement " + i);
+ }
+ }
+
+ //StatusPrinter.print(lc.getStatusManager());
+ }
+}
Added: logback/trunk/logback-examples/src/main/java/chapter6/turboFilters.xml
==============================================================================
--- (empty file)
+++ logback/trunk/logback-examples/src/main/java/chapter6/turboFilters.xml Mon Dec 4 15:25:04 2006
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<configuration>
+
+ <turboFilter class="ch.qos.logback.classic.turbo.MDCFilter">
+ <MDCKey>username</MDCKey>
+ <Value>sebastien</Value>
+ <OnMatch>ACCEPT</OnMatch>
+ </turboFilter>
+
+ <turboFilter class="ch.qos.logback.classic.turbo.MarkerFilter">
+ <Marker>billing</Marker>
+ <OnMatch>DENY</OnMatch>
+ </turboFilter>
+
+ <appender name="console" class="ch.qos.logback.core.ConsoleAppender">
+ <layout class="ch.qos.logback.classic.PatternLayout">
+ <Pattern>%date [%thread] %-5level %logger - %msg%n</Pattern>
+ </layout>
+ </appender>
+
+ <root>
+ <level value="info"/>
+ <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 Dec 4 15:25:04 2006
@@ -56,13 +56,16 @@
<code>TurboFilter</code>.
</p>
+ <h2>Logback Classic</h2>
+
<a name="Filter" />
<p><code>Filter</code> subclasses all implement the
<a href="../xref/ch/qos/logback/core/filter/Filter.html"><code>Filter</code></a>
- abscract class.
+ abscract class. The <code>decide(Object event)</code> method is passed a
+ newly created <code>LoggingEvent</code> object.
</p>
- <h2>Filter chains</h2>
+ <h3>Filter chains</h3>
<p>
This abstract class assumes that filters be organized in a linear chain.
Its member field next points to the next filter in the chain, or
@@ -102,6 +105,7 @@
flexibility in the way that you can affect the logging event's filtering.
</p>
+ <a name="EventEvaluator" />
<h3>Event Evaluators</h3>
<p>
@@ -114,7 +118,7 @@
Let's see a sample configuration.
</p>
-<em>Example 6.1: Basic event evaluator usage</em>
+<em>Example 6.1: Basic event evaluator usage (logback-examples/src/main/java/chapter6/basicEventEvaluator.xml)</em>
<div class="source"><pre><configuration>
<appender name="STDOUT"
@@ -158,9 +162,128 @@
logging event should be accepted, or rejected.
</p>
+
+ <a name="TurboFilter" />
+ <h3>TurboFilters</h3>
+
+ <p>
+ <code>TurboFilter</code> objects all extend the
+ <a href="../xref/ch/qos/logback/classic/turbo/TurboFilter.html">
+ <code>TurboFilter</code></a> abstract class. Like the usual filters, they
+ use ternary logic to return their evaluation of the logging event.
+ </p>
+
+ <p>
+ Overall, they work much like the previously mentionned filters. However,
+ there are two main differences between <code>Filter</code> and
+ <code>TurboFilter</code> objects.
+ </p>
+
+ <p>
+ <code>TurboFilter</code> objects are tied to the logging context. Hence, they
+ are called not only when a given appender is used, but each and every time a logging
+ request is issued. Their scope is wider than appender-attached filters.
+ </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
+ no instanciation, nor any other treatement to provide their
+ filtering functionnalities. They are much more performant than the usual
+ <code>Filter</code> objects.
+ </p>
+
+ <p>
+ Logback classic ships with several <code>TurboFilter</code> classes ready for use.
+ The <code>MDCFilter</code> check the presence of a given value in the MDC. On the other
+ hand, <code>MarkerFilter</code> checks for the presence of a specific marker attached
+ to the logging request.
+ </p>
+
+ <p>
+ Here is a sample configuration, using both <code>MDCFilter</code> and
+ <code>MarkerFilter</code>.
+ </p>
+
+<em>Example 6.1: Basic event evaluator usage (logback-examples/src/main/java/chapter6/turboFilters.xml)</em>
+<div class="source"><pre><configuration>
+
+ <turboFilter class="ch.qos.logback.classic.turbo.MDCFilter">
+ <MDCKey>username</MDCKey>
+ <Value>sebastien</Value>
+ <OnMatch>ACCEPT</OnMatch>
+ </turboFilter>
+
+ <turboFilter class="ch.qos.logback.classic.turbo.MarkerFilter">
+ <Marker>billing</Marker>
+ <OnMatch>DENY</OnMatch>
+ </turboFilter>
+
+ <appender name="console" class="ch.qos.logback.core.ConsoleAppender">
+ <layout class="ch.qos.logback.classic.PatternLayout">
+ <Pattern>%date [%thread] %-5level %logger - %msg%n</Pattern>
+ </layout>
+ </appender>
+
+ <root>
+ <level value="info"/>
+ <appender-ref ref="console" />
+ </root>
+</configuration></pre></div>
+
+ <p>
+ You can see this configuration in action by issuing the following command:
+ </p>
+
+<div class="source"><pre>
+java chapter6.FilterEvents src/java/main/chapter6/turboFilters.xml
+</pre></div>
+
+ <p>
+ The <code>FilterEvents</code> class creates 10 logging requests,
+ each with its number from 01 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>.
+ 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>.
+ </p>
+
+ <p>
+ Here is the output of the previous command:
+ </p>
+
+<div class="source"><pre>
+2006-12-04 15:17:22,859 [main] INFO chapter6.FilterEvents - logging statement 0
+2006-12-04 15:17:22,875 [main] INFO chapter6.FilterEvents - logging statement 1
+2006-12-04 15:17:22,875 [main] INFO chapter6.FilterEvents - logging statement 2
+2006-12-04 15:17:22,875 [main] DEBUG chapter6.FilterEvents - logging statement 3
+2006-12-04 15:17:22,875 [main] INFO chapter6.FilterEvents - logging statement 4
+2006-12-04 15:17:22,875 [main] INFO chapter6.FilterEvents - logging statement 5
+2006-12-04 15:17:22,875 [main] INFO chapter6.FilterEvents - logging statement 7
+2006-12-04 15:17:22,875 [main] INFO chapter6.FilterEvents - logging statement 8
+2006-12-04 15:17:22,875 [main] INFO chapter6.FilterEvents - logging statement 9
+</pre></div>
+
+
+ <p>
+ One can see that the 3rd request, who should not be displayed if we
+ only followed the overall <em>INFO</em> level, appears anyway, because
+ it matched the first <code>TurboFilter</code> requirements and was accepted.
+ </p>
+
+ <p>
+ On the other hand, the 6th request, that is a <em>ERROR</em> level request
+ should have been displayed. But it satisfied the second <code>TurboFilter</code>
+ whose op was <span class="option">OnMatch</span> option is set to <em>DENY</em>.
+ Thus, the 6th request was not displayed.
+ </p>
+ <h2>Logback Access</h2>
+ <h3>Filters</h3>
More information about the logback-dev
mailing list