[logback-dev] svn commit: r1777 - in logback/trunk: logback-examples/src/main/java/chapter4 logback-site/src/site/pages logback-site/src/site/pages/manual
noreply.ceki at qos.ch
noreply.ceki at qos.ch
Mon Aug 25 21:54:06 CEST 2008
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>
More information about the logback-dev
mailing list