Author: ceki Date: Mon Aug 25 21:54:06 2008 New Revision: 1777 Modified: logback/trunk/logback-examples/src/main/java/chapter4/ExitWoes1.java logback/trunk/logback-site/src/site/pages/jmxConfig.html logback/trunk/logback-site/src/site/pages/manual/appenders.html logback/trunk/logback-site/src/site/pages/manual/contextSelector.html logback/trunk/logback-site/src/site/pages/manual/filters.html logback/trunk/logback-site/src/site/pages/manual/joran.html logback/trunk/logback-site/src/site/pages/manual/layouts.html logback/trunk/logback-site/src/site/pages/manual/mdc.html Log: Related to LBSITE-16 Documentation improvements many of which have been proposed by Anton Tagunov. Modified: logback/trunk/logback-examples/src/main/java/chapter4/ExitWoes1.java ============================================================================== --- logback/trunk/logback-examples/src/main/java/chapter4/ExitWoes1.java (original) +++ logback/trunk/logback-examples/src/main/java/chapter4/ExitWoes1.java Mon Aug 25 21:54:06 2008 @@ -1,7 +1,7 @@ /** - * Logback: the reliable, generic, fast and flexible logging framework. + * Logback: the generic, reliable, fast and flexible logging framework. * - * Copyright (C) 1999-2006, QOS.ch + * Copyright (C) 2000-2008, QOS.ch * * This library is free software, you can redistribute it and/or modify it under * the terms of the GNU Lesser General Public License as published by the Free @@ -25,7 +25,7 @@ public static void main(String[] args) throws Exception { LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory(); - lc.shutdownAndReset();//this is to cancel default-config. + lc.shutdownAndReset(); // we want to override the default-config. WriterAppender<LoggingEvent> writerAppender = new WriterAppender<LoggingEvent>(); writerAppender.setContext(lc); writerAppender.setLayout(new EchoLayout<LoggingEvent>()); Modified: logback/trunk/logback-site/src/site/pages/jmxConfig.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/jmxConfig.html (original) +++ logback/trunk/logback-site/src/site/pages/jmxConfig.html Mon Aug 25 21:54:06 2008 @@ -23,45 +23,45 @@ <h2>JMX Configurator</h2> - <p> - As of version 0.8, logback ships with a component that allows - configuration via JMX. Basically, it lets you reload the current - configuration, load a new one, list loggers and modify logger levels. + <p>As of version 0.8, logback ships with a component that allows + configuration via JMX. Basically, it lets you reload the current + configuration, load a new one, list loggers and modify logger + levels. </p> <h3>Configuring your server</h3> - <p> - The first step is to make sure that your application server will - allow the JMX Configurator to publish itself. In this document, - we'll cover the necessary steps in Tomcat and Jetty. + + <p>The first step is to make sure that your application server + will allow the JMX Configurator to publish itself. In this + document, we'll cover the necessary steps in Tomcat and Jetty. </p> <h4>Configuring Tomcat</h4> - <p> - Accessing JMX components with Tomcat requires to add the following lines - to the <em>$TOMCAT_HOME/bin/catalina.sh</em> configuration file: + + <p>Accessing JMX components with Tomcat requires to add the + following lines to the <em>$TOMCAT_HOME/bin/catalina.sh</em> + configuration file: </p> <div class="source"><pre>CATALINA_OPTS="-Dcom.sun.management.jmxremote" CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.ssl=false" CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.authenticate=false"</pre></div> - <p> - Once started with these options, Tomcat's JMX compoenents can be accessed - with JConsole by issuing the following command in a shell: + <p>Once started with these options, Tomcat's JMX compoenents can + be accessed with JConsole by issuing the following command in a + shell: </p> <div class="source"><pre>jconsole &</pre></div> - <p> - You might prefer to access your components via a web-based solution using MX4J. - In that case, here are the required steps: + <p>You might prefer to access your components via a web-based + solution using MX4J. In that case, here are the required steps: </p> - <p> - First, <a href="http://mx4j.sourceforge.net/">download MX4J</a>. - Place the <em>mx4j-impl.jar</em> file in - the <em>$TOMCAT_HOME/bin/</em> directory, and the <em>mx4j-tools.jar</em> - in the <em>$TOMCAT_HOME/common/lib/</em> directory. + <p>First, <a href="http://mx4j.sourceforge.net/">download + MX4J</a>. Place the <em>mx4j-impl.jar</em> file in the + <em>$TOMCAT_HOME/bin/</em> directory, and the + <em>mx4j-tools.jar</em> in the <em>$TOMCAT_HOME/common/lib/</em> + directory. </p> <p>Then, add the following lines to the @@ -87,19 +87,17 @@ mx.httpPort="8082" protocol="AJP/1.3" /></pre></div> - <p> - Once Tomcat is started, you should be ableo to reach the JMX components by - pointing a browser to the following URL: + <p>Once Tomcat is started, you should be able to reach the JMX + components by pointing a browser to the following URL: </p> <div class="source"><pre>http://host_name:8082/</pre></div> <h4>Configuring Jetty</h4> - <p> - Configuring Jetty to publish JMX components requires a few modifications to the - <em>$JETTY_HOME/etc/jetty.xml</em> configuration file. Here are the elements that need to be - added: + <p>Configuring Jetty to publish JMX components requires a few + modifications to the <em>$JETTY_HOME/etc/jetty.xml</em> + configuration file. Here are the elements that need to be added: </p> <div class="source"><pre><Call id="MBeanServer" class="java.lang.management.ManagementFactory" name="getPlatformMBeanServer"/> @@ -116,18 +114,17 @@ </Call> </Get></pre></div> - <p> - Once Jetty is started with this configuration, all available components can be reviewed - at this address: + <p>Once Jetty is started with this configuration, all available + components can be reviewed at this address: </p> <div class="source"><pre>http://host_name:8082/</pre></div> <h3>Using the JMX Configurator</h3> - <p> - The next step is to declare the JMX Configurator in the logback configuration - file. This is done by adding a single element, as shown below: + <p>The next step is to declare the JMX Configurator in the logback + configuration file. This is done by adding a single element, as + shown below: </p> <div class="source"><pre><configuration> @@ -146,58 +143,49 @@ </root> </configuration></pre></div> - <p> - Once the JMX Configurator is displayed on your screen, there are - several operations available. + <p>Once the JMX Configurator is displayed on your screen, there + are several operations available. </p> <ul> - <p>Display the logback Statuses - </p> - <p>Reload the configuration using the same file that was previously - used. - </p> - <p>Reload the configuration using a file whose path is passed as - a parameter.</p> - <p> - Reload the configuration using a file whose URL is passed as a - parameter. - </p> - <p> - Get the level of a logger - </p> - <p> - Change the level setting of a specified logger. - </p> - <p> - Change a list of all declared loggers. - </p> - <p> - Change the level setting of a specified logger. - </p> + <li>Display the logback Status </li> + + <li>Reload the configuration using the same file that was previously + used. </li> + + <li>Reload the configuration using a file whose path is passed + as a parameter.</li> + + <li>Reload the configuration using a file whose URL is passed as + a parameter.</li> + + <li>Get the level of a logger</li> + <li>Change the level setting of a specified logger.</li> + <li>Change a list of all declared loggers.</li> + <li>Change the level setting of a specified logger.</li> </ul> - <p> - In the last case, you must specify the name of the logger you wish to - alter, and its new level. + <p>In the last case, you must specify the name of the logger you + wish to alter, and its new level. </p> - <p> - The level of a logger is a value that can be null, if no specific level - has been configured for said logger. Its effective level, on the other - hand, is given with respect to the parent loggers' levels. This value cannot - be null, since all loggers are direct or indirect children of the root - logger, whose level is always set. When trying to get the level or effective - level of a logger, the name of the logger has to be passed as a parameter. - Note that trying to get the level or effective level for a nonexistent logger - will not return any result. + + <p>The level of a logger is a value that can be null, if no + specific level has been configured for said logger. Its effective + level, on the other hand, is given with respect to the parent + loggers' levels. This value cannot be null, since all loggers are + direct or indirect children of the root logger, whose level is + always set. When trying to get the level or effective level of a + logger, the name of the logger has to be passed as a parameter. + Note that trying to get the level or effective level for a + nonexistent logger will not return any result. </p> - <p> - Displaying logback Statuses via JMX can help users check the internal state - of logback. It shows if anything has gone wrong, if rollovers occured - as expected, and many other useful informations. It is also very useful - when reloading a configuration, since the user can immediately see if - the configuration file was successfully processed. + <p>Displaying logback status via JMX can help users check the + internal state of logback. It shows if anything has gone wrong, if + rollovers occured as expected, as well as other useful + information. It is also very useful when reloading a + configuration, since the user can immediately see if the + configuration file has been procsseds successfully. </p> Modified: logback/trunk/logback-site/src/site/pages/manual/appenders.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/manual/appenders.html (original) +++ logback/trunk/logback-site/src/site/pages/manual/appenders.html Mon Aug 25 21:54:06 2008 @@ -298,9 +298,10 @@ import java.io.OutputStream; import java.io.OutputStreamWriter; -import org.slf4j.Logger; + import org.slf4j.LoggerFactory; +import ch.qos.logback.classic.Logger; import ch.qos.logback.classic.LoggerContext; import ch.qos.logback.core.WriterAppender; import ch.qos.logback.core.layout.EchoLayout; @@ -309,16 +310,19 @@ public static void main(String[] args) throws Exception { LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory(); + lc.shutdownAndReset(); // we want to override the default-config. WriterAppender<LoggingEvent> writerAppender = new WriterAppender<LoggingEvent>(); writerAppender.setContext(lc); - writerAppender.setLayout(new EchoLayout<LoggingEvent>()); + writerAppender.setLayout(new EchoLayout<<LoggingEvent>()); OutputStream os = new FileOutputStream("exitWoes1.log"); writerAppender.setWriter(new OutputStreamWriter(os)); writerAppender.setImmediateFlush(false); writerAppender.start(); + Logger root = lc.getLogger(LoggerContext.ROOT_NAME); + root.addAppender(writerAppender); - Logger logger = LoggerFactory.getLogger(ExitWoes1.class); + Logger logger = lc.getLogger(ExitWoes1.class); logger.debug("Hello world."); } @@ -681,11 +685,10 @@ </p> <p>The <span class="option">FileNamePattern</span> option represents - the file name pattern for the archived (rolled over) log files. The - <span class="option">FileNamePattern</span> option, which is also - required, must include an integer token, that is the string + the file name pattern for the archived (rolled over) log files. + This option is required and must include an integer token <em>%i</em> somewhere within the pattern. - </p> + </p> <p>Here are the available options for <code>FixedWindowRollingPolicy</code> @@ -865,14 +868,13 @@ </p> <p><span class="option">FileNamePattern</span> option defines the - name of the rolled (archived) log files. Its value <span - class="option">FileNamePattern</span> should consist of the name of - the file, plus a suitably placed <em>%d</em> conversion specifier. - The <em>%d</em> conversion specifier may contain a date-and-time - pattern as specified by the <code>java.text.SimpleDateFormat</code> - class. If the date-and-time pattern is omitted, then the default - pattern <em>yyyy-MM-dd</em> is assumed. The following examples - should clarify the point. + name of the rolled (archived) log files. Its value should consist of + the name of the file, plus a suitably placed <em>%d</em> conversion + specifier. The <em>%d</em> conversion specifier may contain a + date-and-time pattern as specified by the + <code>java.text.SimpleDateFormat</code> class. If the date-and-time + pattern is omitted, then the default pattern <em>yyyy-MM-dd</em> is + assumed. The following examples should clarify the point. </p> <table class="bodyTable"> Modified: logback/trunk/logback-site/src/site/pages/manual/contextSelector.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/manual/contextSelector.html (original) +++ logback/trunk/logback-site/src/site/pages/manual/contextSelector.html Mon Aug 25 21:54:06 2008 @@ -207,7 +207,7 @@ <div class="source"><pre><listener> <listener-class>ch.qos.logback.classic.selector.servlet.ContextDetachingSCL</listener-class> -</listener</pre></div> +</listener></pre></div> <p>Using the <code>ContextJNDISelector</code> might slow down your Modified: logback/trunk/logback-site/src/site/pages/manual/filters.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/manual/filters.html (original) +++ logback/trunk/logback-site/src/site/pages/manual/filters.html Mon Aug 25 21:54:06 2008 @@ -54,48 +54,55 @@ <h2>Logback Classic</h2> <a name="Filter"></a> - <p><code>Filter</code> objects all implement the - <a href="../xref/ch/qos/logback/core/filter/Filter.html"><code>Filter</code></a> - abstract class. The <code>decide(Object event)</code> method is passed a - newly created <code>LoggingEvent</code> object. + + <p><code>Filter</code> objects all extend the <a + href="../xref/ch/qos/logback/core/filter/Filter.html"><code>Filter</code></a> + abstract 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>This abstract class assumes that filters are 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>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 <a + href="../xref/ch/qos/logback/core/spi/FilterReply.html"><code>FilterReply</code></a> + enumeration values, i.e. one of <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-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>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> <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>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> @@ -168,14 +175,14 @@ <h3>Logback Filters</h3> - <p> - As the moment, there are two filters that ship with logback. - <a href="../xref/ch/qos/logback/classic/LevelFilter.html"> - <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>At the moment, there are two filters that ship with logback. <a + href="../xref/ch/qos/logback/classic/LevelFilter.html"> + <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: Sample LevelFilter configuration (logback-examples/src/main/java/chapter6/LevelFilterConfig.xml)</em> @@ -227,131 +234,89 @@ </root> </configuration></pre></div> - <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> 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> - or <code>AbstractMatcherFilter</code> classes. - </p> - - <a name="EventEvaluator"></a> - <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.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("billing")</expression> - </evaluator> - <OnMismatch>NEUTRAL</OnMismatch> - <OnMatch>DENY</OnMatch> - </filter></b> - <layout class="ch.qos.logback.classic.PatternLayout"> - <pattern> - %-4relative [%thread] %-5level %logger - %msg%n - </pattern> - </layout> - </appender> + <h3>Evaluator Filters taking Java Expressions</h3> - <root> - <level value="INFO" /> - <appender-ref ref="STDOUT" /> - </root> -</configuration></pre></div> + + <p>A special category of filters is implemented by the <a + href="../xref/ch/qos/logback/core/filter/EvaluatorFilter.html"> + <code>EvaluatorFilter</code></a> class. These filters use an <a + href="../xref/ch/qos/logback/core/boolex/EventEvaluator.html"> + <code>EventEvaluator</code></a> object to decide wether to accept + or deny a request. This allows unprecedented flexibility in the + way that you can affect filtering of logging events. + </p> - <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 defined implicitly. Logback provides - access to the internal components of a logging event and lets the user build her - expression at will. + <p>As a user, you do not need to worry about the actual + plumbing. All you need to do is to give a name to the evaluator + and to specify an <em>evaluation expression</em>, that is a + boolean expression in regular Java syntax. These evaluation + expressions are compiled on-the-fly during the interpretation of + the configration file. It is the users reponsibility to ensure + that the expression is boolean, that it evaluates to true or + false. In evaluation expressions, logback implicitly exposes + various fields of a logging event as variables. The list of these + implicit variables is given below. The scope of evaluation + expressions is limited to the logging event. </p> - <p> - The implicit variables available to the <code>EventEvaluator</code> are described below: - </p> - <table> - <tr> - <th>Name</th> - <th>Type</th> - <th>Description</th> + <table class="bodyTable"> + <tr> + <th>Name</th> + <th>Type</th> + <th>Description</th> </tr> - <tr> - <td>event - </td> + <tr> + <td>event</td> <td><code>LoggingEvent</code></td> - <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> + + <td>The raw 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 + described next. + </td> </tr> - <tr> - <td>message - </td> - <td><code>String</code></td> - <td>The message created with the logging request. - </td> + + <tr class="alt"> + <td>message</td> + <td><code>String</code></td> + <td>The message of the logging request.</td> </tr> <tr> - <td>logger - </td> + <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 when serialized. - </td> + <td>This object is a proxy for the logger object where the + logging request was issued. It can be viewed as a regular + logger object. However, it has some nice performance + properties, especially with respect to serialization. + </td> </tr> - <tr> - <td>level - </td> + + <tr class="alt"> + <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 > INFO</em> is a correct expression. + <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 > + 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>The timestamp corresponding to the logging event's + creation. </td> </tr> - <tr> - <td>marker - </td> + <tr class="alt"> + <td>marker</td> <td><code>Marker</code></td> - <td>The <code>Marker</code> object associated with the logging request. + <td>The <code>Marker</code> object associated with the logging + request. </td> </tr> <tr> @@ -363,43 +328,74 @@ following expression: <em>mdc.get("myKey")</em>. </td> </tr> - <tr> - <td>throwable - </td> + <tr class="alt"> + <td>throwable</td> <td><code>Throwable</code></td> - <td>The exception that was passed to the logger when it - was requested. + <td>The exception associated with the logging event </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 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> - - <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>The behaviour of the <code>EvaluatorFilter</code> is also + affected by its <span class="option">OnMatch</span> and <span + class="option">OnMismatch</span> options taking values of type + <code>FilterReply</code>, i.e. DENY, ACCEPT, NEUTRAL. + </p> + + <p>Here is a concrete example.</p> + +<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><span class="green">message.contains("billing")</span></expression> + </evaluator> + <OnMismatch>NEUTRAL</OnMismatch> + <OnMatch>DENY</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 injected into the + <code>EvaluatorFilter</code>. The <em>expression</em> element + corresponds to the evaluation expression described previously. The + expression <code>message.contains("billing")</code> returns a + boolean value. Notice that the <em>message</em> variable is + defined implicitly. + </p> + + <p>This evalutor filter will drop all logging events whose message + contains the string "billing". + </p> + + <p>The <a + href="../xref/chapter6/FilterEvents.html"><code>FilterEvents</code></a> + class issues ten logging requests, numbered from 0 to 9. Let us + rist run <code>FilterEvents</code> class without any filters: </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> + <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 @@ -412,27 +408,15 @@ 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>Suppose that we want to get rid of the billing information. + The <em>basicEventEvaluator.xml</em> configuration file just + desribed, does exactly what we want.</p> + + <p>Running with filters:</p> + <p class="source">java chapter6.FilterEvents src/main/java/chapter6/basicEventEvaluator.xml</p> + <p>we obtain: </p> <div class="source"><pre>0 [main] INFO chapter6.FilterEvents - logging statement 0 @@ -468,12 +452,12 @@ request is issued. Their scope is wider than appender-attached filters. </p> - <p> - 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>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 instantiation, 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> @@ -663,33 +647,34 @@ </p> - <h2>Logback Access</h2> + <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>. - Thus, a customized filter - for logback access is follows strictly the same rules than one for the - classic module, except for the event implemenation recieved as a parameter. - On the other hand, - <code>TurboFilter</code> objects are not available to the access module. + <p>Logback-access offers most of the features available with + logback-classic. <code>Filter</code> objects are available and + work in the same way as their logback-classic counterparts. They + handle access' implementation of logging events: + <code>AccessEvent</code>. Thus, a customized filter for logback + access follows strictly the same rules as those for + logback-classic, except for the event type recieved as parameter. + On the other hand, <code>TurboFilter</code> objects are supported + by logback-access. </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> object 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><code>EvaluatorFilter</code> objects with java expressions + supplied in in <code>evaluator</code> configuration elements are + supported by logback-access. However, list implicit variables + available for constructing an expression are different. Only the + <code>AccessEvent</code> object can be used by inserting the + <em>event</em> variable in the expression. Nevertheless the access + <code>evaluator</code> is just as powerfull. All the request and + response components are reachable from the <em>event</em> + variable. </p> - <p> - Here is a sample configuration that will ensure that any 404 error will be displayed: + <p>Here is a sample configuration that will ensure that any 404 + error will be logged: </p> <em>Example 6.9: Access Evaluator (logback-examples/src/main/java/chapter6/accessEventEvaluator.xml)</em> @@ -714,10 +699,9 @@ <appender-ref ref="STDOUT" /> </configuration></pre></div> - <p> - We might imagine a slightly more complex use of filters to ensure the display of 404 errors, but - to prevent polluting the output with endless accesses to CSS files. Here is what such a configuration - would look like: + <p>We might imagine a slightly more complex use of filters to + ensure logging of 404 errors, except those returned on access to + CSS resources. Here is what such a configuration would look like: </p> <em>Example 6.10: Access Evaluator (logback-examples/src/main/java/chapter6/accessEventEvaluator2.xml)</em> Modified: logback/trunk/logback-site/src/site/pages/manual/joran.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/manual/joran.html (original) +++ logback/trunk/logback-site/src/site/pages/manual/joran.html Mon Aug 25 21:54:06 2008 @@ -460,7 +460,8 @@ the root logger is already named, it does not admit a name attribute either. The value of the level attribute can be set to one of the case-insensitive strings TRACE, DEBUG, INFO, WARN, ERROR, ALL or - OFF. Note that the level of the root logger cannot be inherited. + OFF. Note that the level of the root logger cannot be set to + INHERITED or NULL. </p> @@ -992,16 +993,15 @@ <div class="source"><pre>USER_HOME=/home/sebastien</pre></div> <p>Nested variabled subsitution is also supported. By nested, we - mean that the value definition of a variable contains referenced to - other variables. Here is an example. Suppose you wish to use - variables to specify not only the destination directory but also - the file name, and combine those variable in a third variable - called "destination". The properties file shown below gives an - example. + mean that the value definition of a variable contains references to + other variables. Suppose you wish to use variables to specify not + only the destination directory but also the file name, and combine + those two variables in a third variable called "destination". The + properties file shown below gives an example. </p> - <em>Example 3.<span class="autoEx"/>: Recursive use of variables + <em>Example 3.<span class="autoEx"/>: Nested variable references (logback-examples/src/main/java/chapter3/variables2.properties)</em> <div class="source"><pre>USER_HOME=/home/sebastien Modified: logback/trunk/logback-site/src/site/pages/manual/layouts.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/manual/layouts.html (original) +++ logback/trunk/logback-site/src/site/pages/manual/layouts.html Mon Aug 25 21:54:06 2008 @@ -1414,12 +1414,16 @@ <a name="ClassicHTMLLayout"></a> - <h3>HTMLLayout</h3> - - <p><a href="../xref/ch/qos/logback/classic/html/HTMLLayout.html"> - <code>HTMLLayout</code></a> outputs logging events in an HTML - table where each row of the table corresponds to a logging - event.</p> + <h2>Generating logs in HTML format</h2> + + <p>Logback provides a special <a + href="../xref/ch/qos/logback/core/Layout.html"><code>Layout</code></a>, + namely <a + href="../xref/ch/qos/logback/classic/html/HTMLLayout.html"> + <code>HTMLLayout</code></a>, to generate logs directly in HTML + format. <code>HTMLLayout</code> outputs logging events in an HTML + table where each row of the table corresponds to a logging + event.</p> <p>Here is a sample output produced by <code>HTMLLayout</code> using its default CSS stylesheet:</p> @@ -1438,11 +1442,11 @@ <code>PatternLayout</code> with <code>HTMLLayout</code> is that conversion specifiers should not be separated by space characters or more generally by literal text. Each specifier found in the - pattern willa result in a separate column, in particular for each - literal text in the pattern, wasting valuable real estate on your - screen. - </p> - + pattern will result in a separate column. Likewise a separate + column will be generated for each block of literal text found in + the pattern potentially wasting valuable real estate on your + screen.</p> + <p>Here is simple but functional configuration file illustrating the use of <code>HTMLLayout</code>. </p> @@ -1488,18 +1492,19 @@ <h3>Stack traces</h3> - <p> If you use the <em>%em</em> conversion word, to display stack - traces, a table column will be created to display exception stack - traces. In most cases the column will be empty, wasting screen + <p> If you use the <em>%em</em> conversion word to display stack + traces, a table column will be created to display stack traces. In + most cases the column will be empty, wasting screen real-estate. Moreover, printing a stack trace on a separate column - does yield very readable results. Fortunately, the <em>%ex</em> - conversion word is not the only way to display stack traces. + does not yield very readable results. Fortunately, the + <em>%ex</em> conversion word is not the only way to display stack + traces. </p> <p>A better solution is available through implementations of <code>IThrowableRenderer</code> interface. Such an implementation - can assigned to <code>HTMLLayout</code> to manage the display data - related to exceptions. By default, a + can be assigned to <code>HTMLLayout</code> to manage the display + data related to exceptions. By default, a <a href="../xref/ch/qos/logback/classic/html/DefaultThrowableRenderer.html"> <code>DefaultThrowableRenderer</code></a> is assigned to each <code>HTMLLayout</code> instance. It writes exceptions on a @@ -1508,12 +1513,12 @@ </p> <p>If for some reason, you still wish to use the <em>%ex</em> - pattern, then you can specify - <a href="../xref/ch/qos/logback/core/html/NOPThrowableRenderer.html"> - <code>NOPThrowableRenderer</code></a> in the configuration file - in order to disable displaying a separate row for the stack - trace. We don't have the faintest idea why you would want to do - that, but if you did, you could. + pattern, then you can specify <a + href="../xref/ch/qos/logback/core/html/NOPThrowableRenderer.html"> + <code>NOPThrowableRenderer</code></a> in the configuration file in + order to disable displaying a separate row for the stack trace. We + don't have the faintest idea why you would want to do that, but if + you wished, you could. </p> <h3>CSS</h3> @@ -1522,8 +1527,8 @@ is controlled through a Cascading Style Sheet (CSS). In the absence of specific instructions, <code>HTMLLayout</code> will default to its internal CSS. However, your can instruct - <code>HTMLLayout</code> you use an external CSS file. For this - purpose, a <code>cssBuilder</code> element can be nested within a + <code>HTMLLayout</code> to use an external CSS file. For this + purpose a <code>cssBuilder</code> element can be nested within a <code><layout></code> element, as shown below. </p> @@ -1600,268 +1605,249 @@ <a name="AccessPatternLayout"></a> <h3>PatternLayout</h3> - <p> <a href="../xref/ch/qos/logback/access/PatternLayout.html"> + + <p><a href="../xref/ch/qos/logback/access/PatternLayout.html"> <code>PatternLayout</code></a> in logback-access can be configured - in the same way as it's classic counterpart, with the notable - exception of the available conversion specifiers, as appropriate - for HTTP servlet request and response. - </p> + much in the same way as its classic counterpart. However it + features additional conversion specifiers suited for logging + particular bits of information availalbe only in HTTP servlet + requests and HTTP servlet responses. + </p> <p>Below is a list of conversion specifiers for <code>PatternLayout</code> in logback-access.</p> <table class="bodyTable" border="0" CELLPADDING="8"> - <th align="center">Conversion Word</th> - <th align="center">Effect</th> - - <tr class="a"> - <td align="center"><b>a / remoteIP</b></td> - <td> - <p> - Remote IP address. - </p> - </td> - </tr> - <tr class="b"> - <td align="center"><b>A / localIP</b></td> - <td> - <p> - Local IP address. - </p> - </td> - </tr> - <tr class="a"> - <td align="center"><b>b / B / byteSent</b></td> - <td> - <p> - Response's content length. - </p> - </td> - </tr> - <tr class="b"> - <td align="center"><b>h / clientHost</b></td> - <td> - <p> - Remote host. - </p> - </td> - </tr> - <tr class="a"> - <td align="center"><b>H / protocol</b></td> - <td> - <p> - Request protocol. - </p> - </td> - </tr> - <tr class="b"> - <td align="center"><b>l</b></td> - <td> - <p> - Remote log name. In logback-access, this converter always - returns the value "-". - </p> - </td> - </tr> - - <tr class="a"> - <td align="center"><b>reqParameter{paramName}</b></td> - <td> - <p> - Parameter of the response. - </p> - <p>This conversion word takes the first option in braces and looks - for the corresponding parameter in the request.</p> - <p><b>%reqParameter{input_data}</b> - displays the corresponding parameter.</p> - </td> - </tr> - <tr class="b"> - <td align="center"><b>i{header} / header{header}</b></td> - <td> - <p> - Request header. - </p> - <p>This conversion word takes the first option in braces and looks - for the corresponding header in the request.</p> - <p><b>%header{Referer}</b> displays the referer of the request.</p> - <p> - If no option is specified, it displays every available header. - </p> - </td> - </tr> - <tr class="a"> - <td align="center"><b>m / requestMethod</b></td> - <td> - <p> - Request method. - </p> - </td> - </tr> - <tr class="b"> - <td align="center"><b>r / requestURL</b></td> - <td> - <p> - URL requested. - </p> - </td> - </tr> - <tr class="a"> - <td align="center"><b>s / statusCode</b></td> - <td> - <p> - Status code of the request. - </p> - </td> - </tr> - <tr class="b"> - <td align="center"><b>t / date</b></td> - <td> - <p> - Used to output the date of the logging event. - The date conversion specifier may be followed by - a set of braces containing a date and time - pattern strings used by - <code>java.text.SimpleDateFormat</code> - . - <em>ABSOLUTE</em> - , - <em>DATE</em> - or - <em>ISO8601</em> - can also be used. + <tr> + <th align="center">Conversion Word</th> + <th align="center">Effect</th> + </tr> + <tr class="a"> + <td align="center"><b>a / remoteIP</b></td> + <td> + <p> + Remote IP address. + </p> + </td> + </tr> + <tr class="b"> + <td align="center"><b>A / localIP</b></td> + <td> + <p> + Local IP address. + </p> + </td> + </tr> + <tr class="a"> + <td align="center"><b>b / B / byteSent</b></td> + <td> + <p> + Response's content length. + </p> + </td> + </tr> + <tr class="b"> + <td align="center"><b>h / clientHost</b></td> + <td> + <p> + Remote host. + </p> + </td> + </tr> + <tr class="a"> + <td align="center"><b>H / protocol</b></td> + <td> + <p> + Request protocol. + </p> + </td> + </tr> + <tr class="b"> + <td align="center"><b>l</b></td> + <td> + <p> + Remote log name. In logback-access, this converter always + returns the value "-". + </p> + </td> + </tr> + + <tr class="a"> + <td align="center"><b>reqParameter{paramName}</b></td> + <td> + <p> + Parameter of the response. + </p> + <p>This conversion word takes the first option in braces and looks + for the corresponding parameter in the request.</p> + <p><b>%reqParameter{input_data}</b> + displays the corresponding parameter.</p> + </td> + </tr> + <tr class="b"> + <td align="center"><b>i{header} / header{header}</b></td> + <td> + <p> + Request header. + </p> + <p>This conversion word takes the first option in braces and looks + for the corresponding header in the request.</p> + <p><b>%header{Referer}</b> displays the referer of the request.</p> + <p> + If no option is specified, it displays every available header. + </p> + </td> + </tr> + <tr class="a"> + <td align="center"><b>m / requestMethod</b></td> + <td> + <p> + Request method. + </p> + </td> + </tr> + <tr class="b"> + <td align="center"><b>r / requestURL</b></td> + <td> + <p> + URL requested. + </p> + </td> + </tr> + <tr class="a"> + <td align="center"><b>s / statusCode</b></td> + <td> + <p> + Status code of the request. + </p> + </td> + </tr> + <tr class="b"> + <td align="center"><b>t / date</b></td> + <td> + <p>Used to output the date of the logging event. The date + conversion specifier may be followed by a set of braces + containing a date and time pattern strings used by + <code>java.text.SimpleDateFormat</code>. <em>ABSOLUTE</em>, + <em>DATE</em> or <em>ISO8601</em> are also valid values. </p> - <p> - For example, - <b>%d{HH:mm:ss,SSS}</b> - , - <b> - %d{dd MMM yyyy ;HH:mm:ss,SSS} - </b> - or - <b>%d{DATE}</b> - . If no date format specifier is given then - ISO8601 format is assumed. + <p>For example, <b>%d{HH:mm:ss,SSS}</b>, + <b>%d{dd MMM yyyy ;HH:mm:ss,SSS}</b> or + <b>%d{DATE}</b>. If no date format specifier is given then + ISO8601 format is assumed. </p> - </td> - </tr> - <tr class="a"> - <td align="center"><b>u / user</b></td> - <td> - <p> - Remote user. - </p> - </td> - </tr> - <tr class="b"> - <td align="center"><b>U / requestURI</b></td> - <td> - <p> - Requested URI. - </p> - </td> - </tr> - <tr class="a"> - <td align="center"><b>v / server</b></td> - <td> - <p> - Server name. - </p> - </td> - </tr> - <tr class="b"> - <td align="center"><b>localPort</b></td> - <td> - <p> - Local port. - </p> - </td> - </tr> - <tr class="a"> - <td align="center"><b>reqAttribute{attributeName}</b></td> - <td> - <p> - Attribute of the request. - </p> - <p>This conversion word takes the first option in braces and looks - for the corresponding attribute in the request.</p> - <p><b>%reqAttribute{SOME_ATTRIBUTE}</b> - displays the corresponding attribute.</p> - </td> - </tr> - <tr class="b"> - <td align="center"><b>reqCookie{cookie}</b></td> - <td> - <p> - Request cookie. - </p> - <p>This conversion word takes the first option in braces and looks - for the corresponding cookie in the request.</p> - <p><b>%cookie{COOKIE_NAME}</b> displays corresponding cookie.</p> - </td> - </tr> - <tr class="a"> - <td align="center"><b>responseHeader{header}</b></td> - <td> - <p> - Header of the response. - </p> - <p>This conversion word takes the first option in braces and looks - for the corresponding header in the response.</p> - <p><b>%header{Referer}</b> displays the referer of the response.</p> - </td> - </tr> - <tr class="b"> - <td align="center"><b>requestContent</b></td> - <td> - <p> - This conversion word displays the content of the request, that is the - request's <code>InputStream</code>. It is used in conjunction with a - <a href="../xref/ch/qos/logback/access/servlet/TeeFilter.html"> - <code>TeeFilter</code></a>, a <code>javax.servlet.Filter</code> that - replaces the original <code>HttpServletRequest</code> - by a <a href="../xref/ch/qos/logback/access/servlet/TeeHttpServletRequest.html"> - <code>TeeHttpServletRequest</code></a>. The latter object allows - access to the requet's <code>InputStream</code> multiple times without - any loss of data. - </p> - </td> - </tr> - <tr class="a"> - <td align="center"><b>fullRequest</b></td> - <td> - <p>This converter outputs the data associated with the + </td> + </tr> + <tr class="a"> + <td align="center"><b>u / user</b></td> + <td> + <p> + Remote user. + </p> + </td> + </tr> + <tr class="b"> + <td align="center"><b>U / requestURI</b></td> + <td> + <p> + Requested URI. + </p> + </td> + </tr> + <tr class="a"> + <td align="center"><b>v / server</b></td> + <td> + <p>Server name.</p> + </td> + </tr> + <tr class="b"> + <td align="center"><b>localPort</b></td> + <td> + <p>Local port.</p> + </td> + </tr> + <tr class="a"> + <td align="center"><b>reqAttribute{attributeName}</b></td> + <td> + <p>Attribute of the request.</p> + <p>This conversion word takes the first option in braces and looks + for the corresponding attribute in the request.</p> + <p><b>%reqAttribute{SOME_ATTRIBUTE}</b> + displays the corresponding attribute.</p> + </td> + </tr> + <tr class="b"> + <td align="center"><b>reqCookie{cookie}</b></td> + <td> + <p>Request cookie.</p> + <p>This conversion word takes the first option in braces and looks + for the corresponding cookie in the request.</p> + <p><b>%cookie{COOKIE_NAME}</b> displays corresponding cookie.</p> + </td> + </tr> + <tr class="a"> + <td align="center"><b>responseHeader{header}</b></td> + <td> + <p> + Header of the response. + </p> + <p>This conversion word takes the first option in braces and looks + for the corresponding header in the response.</p> + <p><b>%header{Referer}</b> displays the referer of the response.</p> + </td> + </tr> + <tr class="b"> + <td align="center"><b>requestContent</b></td> + <td> + <p>This conversion word displays the content of the request, + that is the request's <code>InputStream</code>. It is used + in conjunction with a <a + href="../xref/ch/qos/logback/access/servlet/TeeFilter.html"> + <code>TeeFilter</code></a>, a + <code>javax.servlet.Filter</code> that replaces the original + <code>HttpServletRequest</code> by a <a + href="../xref/ch/qos/logback/access/servlet/TeeHttpServletRequest.html"> + <code>TeeHttpServletRequest</code></a>. The latter object + allows access to the requet's <code>InputStream</code> + multiple times without any loss of data. + </p> + </td> + </tr> + <tr class="a"> + <td align="center"><b>fullRequest</b></td> + <td> + <p>This converter outputs the data associated with the request, including all headers and request contents. - </p> - </td> - </tr> - <tr class="b"> - <td align="center"><b>responseContent</b></td> - <td> - <p> - This conversion word displays the content of the response, that is the - response's <code>InputStream</code>. It is used in conjunction with a + </p> + </td> + </tr> + <tr class="b"> + <td align="center"><b>responseContent</b></td> + <td> + <p>This conversion word displays the content of the + response, that is the response's + <code>InputStream</code>. It is used in conjunction with a <a href="../xref/ch/qos/logback/access/servlet/TeeFilter.html"> - <code>TeeFilter</code></a>, a <code>javax.servlet.Filter</code> that - replaces the original <code>HttpServletResponse</code> - by a <a href="../xref/ch/qos/logback/access/servlet/TeeHttpServletResponse.html"> - <code>TeeHttpServletResponse</code></a>. The latter object allows - access to the requet's <code>InputStream</code> multiple times without - any loss of data. - </p> - </td> - </tr> - <tr class="a"> - <td align="center"><b>fullResponse</b></td> - <td> - <p> - This conversion word takes all the available data + <code>TeeFilter</code></a>, a + <code>javax.servlet.Filter</code> that replaces the original + <code>HttpServletResponse</code> by a <a + href="../xref/ch/qos/logback/access/servlet/TeeHttpServletResponse.html"> + <code>TeeHttpServletResponse</code></a>. The latter object + allows access to the requet's <code>InputStream</code> + multiple times without any loss of data. + </p> + </td> + </tr> + <tr class="a"> + <td align="center"><b>fullResponse</b></td> + <td> + <p>This conversion word takes all the available data associatede with the response, inclusing all headers of the response and response contents. - </p> - </td> - </tr> - </table> + </p> + </td> + </tr> + </table> <p>Logback access' <code>PatternLayout</code> also recognize three keywords, which act like shortcuts to a certain pattern.</p> @@ -1887,10 +1873,10 @@ which displays client host, remote log name, user, date, requested URL, status code and response's content length</p> - <p>The <em>combined</em> keyword is a shortcut to - <em>%h %l %u %t \"%r\" %s %b \"%i{Referer}\" \"%i{User-Agent}\"</em>. This pattern begins - much like the <em>common</em> pattern but also displays two request headers, namely - referer, and user-agent.</p> + <p>The <em>combined</em> keyword is a shortcut for <em>%h %l %u %t + \"%r\" %s %b \"%i{Referer}\" \"%i{User-Agent}\"</em>. This pattern + begins much like the <em>common</em> pattern but also displays two + request headers, namely referer, and user-agent.</p> <a name="AccessHTMLLayout"></a> <h3>HTMLLayout</h3> @@ -1898,37 +1884,49 @@ <p>The <a href="../xref/ch/qos/logback/access/html/HTMLLayout.html"><code>HTMLLayout</code></a> class found in logback-access is similar to the <a - href="#ClassicHTMLLayout"><code>HTMLLayout</code></a> class found - in logback-classic. + href="#ClassicHTMLLayout"><code>HTMLLayout</code></a> class from + logback-classic. </p> <p>By default, it will create a table containing the following data:</p> <ul> - <p>Remote IP</p> - <p>Date</p> - <p>Request URL</p> - <p>Status code</p> - <p>Content Length</p> + <li>Remote IP</li> + <li>Date</li> + <li>Request URL</li> + <li>Status code</li> + <li>Content Length</li> </ul> - <p>Here is a sample output produced by <code>HTMLLayout</code> in logback-access:</p> + <p>Here is a sample output produced by <code>HTMLLayout</code> in + logback-access:</p> <img src="images/htmlLayoutAccess.gif" alt="Access HTML Layout Sample Image"/> - <p>What is better than a real world example? Our own log4j + <p>What can be better than a real world example? Our own log4j properties to logback <a href="http://logback.qos.ch/translator/">translator</a> makes use of logback-access to showcase a live ouput, using a <code>RollingFileAppender</code> and <code>HTMLLayout</code>.</p> - <p>You can see the file by <a - href="http://logback.qos.ch/translator/logs/access.html">following - this link</a>.</p> - - <p>Just like any access log, each visit the <a - href="http://logback.qos.ch/translator/">translator</a> - web-application will add a new entry to the access logs. - </p> + <p>What can be better than a real world example? Our own log4j + properties for logback <a + href="http://logback.qos.ch/translator/">translator</a> makes use + of logback-access to demonstrate live ouput from + <code>RollingFileAppender</code> with <code>HTMLLayout</code>.</p> + + + <p>On every new user request to our <a + href="http://logback.qos.ch/translator/">translator</a> + web-application, a new entry will be added to the access logs, + which you can view by <a + href="http://logback.qos.ch/translator/logs/access.html">following + this link</a>.</p> + + + + + + <script src="../templates/footer.js"></script> </div> Modified: logback/trunk/logback-site/src/site/pages/manual/mdc.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/manual/mdc.html (original) +++ logback/trunk/logback-site/src/site/pages/manual/mdc.html Mon Aug 25 21:54:06 2008 @@ -50,12 +50,11 @@ the SLF4J API: Mapped Diagnostic Contexts (MDC). </p> - <p> - To uniquely stamp each request, the user puts contextual - information into the <code><a - href="http://www.slf4j.org/api/org/slf4j/MDC.html">MDC</a></code>, - the abbreviation of Mapped Diagnostic Context. The public - interface of the MDC class is shown below. + <p>To uniquely stamp each request, the user puts contextual + information into the <code><a + href="http://www.slf4j.org/api/org/slf4j/MDC.html">MDC</a></code>, + the abbreviation of Mapped Diagnostic Context. The salient parts + of the MDC class is shown below. </p> <div class="source"><pre>package org.slf4j; @@ -73,9 +72,6 @@ //Clear all entries in the MDC. <b>public static void clear();</b> - - //Returns the keys in the MDC as a Set. The returned value can be null. - <b>public static Set<String> getKeys();</b> }</pre></div> <p>The <code>MDC</code> class contains only static methods. It @@ -615,6 +611,28 @@ are unaffected. Furthermore, any given thread will contain correct MDC data any point in time.</p> + + + <h3>MDC And Managed Threads</h3> + + <p>A copy of mapped diagnostic context can not always be inherited + by worker thread from the initiating thread. This is the case when + <code>java.util.concurrent.Executors</code> is used for thread + management. For instance, <code>newCachedThreadPool</code> method + creates a <code>ThreadPoolExecutor</code> and like other thread + pooling code it has intricate thread creation logic. + </p> + + <p>In such cases, it is recommended that + <code>MDC.getCopyOfContextMap()</code> is invoked on the original + (master) thread before submitting a task to the executor. When the + task runs, as its first action, it should invoke + <code>MDC.setContextMapValues()</code> to associate the stored copy + of the orinal MDC values with the new <code>Executor</code> managed + thread. + </p> + + <script src="../templates/footer.js"></script> </div> </body>