<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&#252;lc&#252;, S&#233;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 &#169; 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>
		
		<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. The <code>decide(Object event)</code> method is passed a
		newly created <code>LoggingEvent</code> object.
		</p>
		
		<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 
			<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>
    
    <a name="EventEvaluator" />
    <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 (logback-examples/src/main/java/chapter6/basicEventEvaluator.xml)</em>
<div class="source"><pre>&lt;configuration>

  &lt;appender name="STDOUT"
    class="ch.qos.logback.core.ConsoleAppender">
    <b>&lt;filter class="ch.qos.logback.core.filter.EvaluatorFilter">
      &lt;evaluator name="myEval">
        &lt;expression>message.contains("important")&lt;/expression>
      &lt;/evaluator>
      &lt;OnMismatch>NEUTRAL&lt;/OnMismatch>
      &lt;OnMatch>ACCEPT&lt;/OnMatch>
    &lt;/filter></b>
    &lt;layout class="ch.qos.logback.classic.PatternLayout">
      &lt;pattern>
        %-4relative [%thread] %-5level %logger - %msg%n
      &lt;/pattern>
    &lt;/layout>
  &lt;/appender>

  &lt;root>
    &lt;level value="INFO" />
    &lt;appender-ref ref="STDOUT" />
  &lt;/root>
&lt;/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 variables available to the <code>EventEvaluator</code> are descripbed below:
		</p>
		
		<table>
			<tr>
				<th>Name</th>
				<th>Type</th>
				<th>Description</th>
			</tr>
			<tr>
				<td>event
				</td>
				<td><code>LoggingEvent</code></td>
				<td>The newly created logging event.
				</td>
			</tr>
			<tr>
				<td>message
				</td>
				<td><code>String</code></td>
				<td>The message created with the logging request.
				</td>
			</tr>
			<tr>
				<td>logger
				</td>
				<td><code>LoggerRemoteView</code></td>
				<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.
				</td>
			</tr>
			<tr>
				<td>level
				</td>
				<td><code>int</code></td>
				<td>The int value corresponding to the level. To help create easily
				expressions involving levels, the default value <em>DEBUG</em>, 
				<em>INFO</em>, <em>WARN</em> and <em>ERROR</em> are also available. Thus,
				using <em>level &gt; INFO</em> is a correct expression.
				</td>
			</tr>
			<tr>
				<td>timeStamp
				</td>
				<td><code>long</code></td>
				<td>The timestamp corresponding to the logging event's creation.
				</td>
			</tr>
			<tr>
				<td>marker
				</td>
				<td><code>Marker</code></td>
				<td>The <code>Marker</code> object associated with the logging request.
				</td>
			</tr>
			<tr>
				<td>mdc
				</td>
				<td><code>Map</code></td>
				<td>A map containing all the MDC values at the time of the 
				creation of the logging event. A value can be access by using the
				following expression: <em>mdc.get("myKey")</em>.
				</td>
			</tr>
			<tr>
				<td>throwable
				</td>
				<td><code>Throwable</code></td>
				<td>The exception that was passed to the logger when it
				was requested.
				</td>
			</tr>
		</table>
		
		<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>
		
		
		<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>&lt;configuration>

  &lt;turboFilter class="ch.qos.logback.classic.turbo.MDCFilter">
    &lt;MDCKey>username&lt;/MDCKey>
    &lt;Value>sebastien&lt;/Value>
    &lt;OnMatch>ACCEPT&lt;/OnMatch>
  &lt;/turboFilter>
	
  &lt;turboFilter class="ch.qos.logback.classic.turbo.MarkerFilter">
    &lt;Marker>billing&lt;/Marker>
    &lt;OnMatch>DENY&lt;/OnMatch>
  &lt;/turboFilter>

  &lt;appender name="console" class="ch.qos.logback.core.ConsoleAppender">
    &lt;layout class="ch.qos.logback.classic.PatternLayout">
      &lt;Pattern>%date [%thread] %-5level %logger - %msg%n&lt;/Pattern>
  &lt;/layout>
  &lt;/appender>

  &lt;root>
    &lt;level value="info"/>
    &lt;appender-ref ref="console" />
  &lt;/root>  
&lt;/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>
    
    <p>
    	Logback access benefits from most of the possibilities available
    	to the classic module. <code>Filter</code> objects are available and work
    	in the same way as their classic counterpart. They handle access' implementation
    	of logging events: <code>AccessEvent</code>. On the other hand,
    	<code>TurboFilter</code> objects are not available to the access module.
    </p>
    
    <h3>Filters</h3>
    
    <p>
    	<code>EvaluatorFilter</code> objects, with their expressions, are available to
    	the access module. However, the variables that one can use to build an expression
    	are different. Only the <code>AccessEvent</code> objects can be used, by inserting the
    	<em>event</em> variable in the expression. Although less wide than its classic
    	counterpart, the access evaluation filter is just as powerfull. All the
    	request and response components are reachable from the <em>event</em> variable.
    </p>    



  </body>
</document>