[logback-dev] svn commit: r1060 - in logback/trunk: logback-examples/src/main/java/chapter6 logback-site/src/site/resources/manual/images/chapter6 logback-site/src/site/xdocTemplates/manual
noreply.seb at qos.ch
noreply.seb at qos.ch
Mon Dec 4 11:55:59 CET 2006
Author: seb
Date: Mon Dec 4 11:55:59 2006
New Revision: 1060
Added:
logback/trunk/logback-examples/src/main/java/chapter6/
logback/trunk/logback-examples/src/main/java/chapter6/basicEventEvaluator.xml
logback/trunk/logback-site/src/site/resources/manual/images/chapter6/
logback/trunk/logback-site/src/site/resources/manual/images/chapter6/filterChain.gif (contents, props changed)
logback/trunk/logback-site/src/site/xdocTemplates/manual/filters.xml
Log:
First draft of chapter 6
Added: logback/trunk/logback-examples/src/main/java/chapter6/basicEventEvaluator.xml
==============================================================================
--- (empty file)
+++ logback/trunk/logback-examples/src/main/java/chapter6/basicEventEvaluator.xml Mon Dec 4 11:55:59 2006
@@ -0,0 +1,23 @@
+<configuration>
+
+ <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>
+ </evaluator>
+ <OnMismatch>NEUTRAL</OnMismatch>
+ <OnMatch>ACCEPT</OnMatch>
+ </filter>
+ <layout class="ch.qos.logback.classic.PatternLayout">
+ <pattern>
+ %-4relative [%thread] %-5level %logger - %msg%n
+ </pattern>
+ </layout>
+ </appender>
+
+ <root>
+ <level value="INFO" />
+ <appender-ref ref="STDOUT" />
+ </root>
+</configuration>
\ No newline at end of file
Added: logback/trunk/logback-site/src/site/resources/manual/images/chapter6/filterChain.gif
==============================================================================
Binary file. No diff available.
Added: logback/trunk/logback-site/src/site/xdocTemplates/manual/filters.xml
==============================================================================
--- (empty file)
+++ logback/trunk/logback-site/src/site/xdocTemplates/manual/filters.xml Mon Dec 4 11:55:59 2006
@@ -0,0 +1,168 @@
+<document>
+<!--
+
+ Warning: do not use any auto-format function on this file.
+ Since "source" divs use pre as white-space, it affects the
+ look of the code parts in this document.
+
+ -->
+
+ <body>
+ <h2>Chapter 6: Filters</h2>
+ <div class="author">
+ Authors: Ceki Gülcü, Sébastien Pennec
+ </div>
+
+ <table>
+ <tr>
+ <td valign="top" align="top">
+ <a rel="license"
+ href="http://creativecommons.org/licenses/by-nc-sa/2.5/">
+ <img alt="Creative Commons License"
+ style="border-width: 0"
+ src="http://creativecommons.org/images/public/somerights20.png" />
+ </a>
+ </td>
+ <td>
+ <p>Copyright © 2000-2006, QOS.ch</p>
+
+ <p>
+ <!--Creative Commons License-->
+ This work is licensed under a
+ <a rel="license"
+ href="http://creativecommons.org/licenses/by-nc-sa/2.5/">
+ Creative Commons
+ Attribution-NonCommercial-ShareAlike 2.5
+ License
+ </a>.
+ <!--/Creative Commons License-->
+ </p>
+ </td>
+ </tr>
+ </table>
+
+ <p>
+ As we have seen, logback has several built-in ways for filtering log requests,
+ including the context-wide filter, logger-level selection rule and appender filters.
+ These provide high performance filtering for the most commonly encountered
+ cases. These filters are largely inspired from Linux ipchains or
+ iptables as they are called in more recent Linux kernels.
+ Logback filters are based on ternary logic allowing them to be assembled or chained
+ together to compose an arbitrarily complex filtering policy.
+ </p>
+
+ <p>
+ There are two main types of filters, namely <code>Filter</code> and
+ <code>TurboFilter</code>.
+ </p>
+
+ <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.
+ </p>
+
+ <h2>Filter chains</h2>
+ <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
+ <code>null</code> if there are no further filters in the chain.
+ Figure 6.1 depicts a sample filter chain consisting of three filters.
+ </p>
+
+ <img src="images/chapter6/filterChain.gif" alt="A sample filter chain"/>
+
+ <p>
+ Filters are based on ternary logic. The <code>decide(Object event)</code>
+ method of each filter is called in sequence. This method returns one of the
+ enumerations <code>FilterReply.DENY</code>, <code>FilterReply.NEUTRAL</code> or
+ <code>FilterReply.ACCEPT</code>. If the returned value is <code>FilterReply.DENY</code>,
+ then the log event is dropped immediately without consulting the
+ remaining filters. If the value returned is <code>FilterReply.NEUTRAL</code>,
+ then the next filter in the chain is consulted. If there are no further filters
+ to consult, then the logging event is processed normally.
+ If the returned value is <code>FilterReply.ACCEPT</code>, then the logging
+ event is processed immediately skipping the remaining filters.
+ </p>
+
+ <p>
+ In logback, <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 NDC,
+ the time of day or any other part of the logging event.
+ </p>
+
+ <p>
+ The criteria can be specified using an expression evaluator. The
+ <a href="../xref/ch/qos/logback/core/filter/EvaluatorFilter.html">
+ <code>EvaluatorFilter</code></a> class uses 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>
+
+ <h3>Event Evaluators</h3>
+
+ <p>
+ Events evaluators allow the user to enter java expressions, using
+ components of a logging event, and to check each logging event
+ against the compiled expression.
+ </p>
+
+ <p>
+ Let's see a sample configuration.
+ </p>
+
+<em>Example 6.1: Basic event evaluator usage</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>
+ </evaluator>
+ <OnMismatch>NEUTRAL</OnMismatch>
+ <OnMatch>ACCEPT</OnMatch>
+ </filter></b>
+ <layout class="ch.qos.logback.classic.PatternLayout">
+ <pattern>
+ %-4relative [%thread] %-5level %logger - %msg%n
+ </pattern>
+ </layout>
+ </appender>
+
+ <root>
+ <level value="INFO" />
+ <appender-ref ref="STDOUT" />
+ </root>
+</configuration></pre></div>
+
+ <p>
+ 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
+ access to the internal components of a logging event and lets the user build her
+ expression at will.
+ </p>
+
+ <p>
+ 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>
+
+
+
+
+
+
+
+ </body>
+</document>
\ No newline at end of file
More information about the logback-dev
mailing list