[logback-dev] svn commit: r660 - in logback/trunk: logback-access/src/main/java/ch/qos/logback/access logback-site/src/site/xdocTemplates
noreply.ceki at qos.ch
noreply.ceki at qos.ch
Tue Oct 10 22:32:15 CEST 2006
Author: ceki
Date: Tue Oct 10 22:32:15 2006
New Revision: 660
Modified:
logback/trunk/logback-access/src/main/java/ch/qos/logback/access/PatternLayout.java
logback/trunk/logback-site/src/site/xdocTemplates/accessLogJetty.xml
Log:
updated docs.
I have not actually checked that the config files included in the docs actually work.
They should be verified at some stage...
Modified: logback/trunk/logback-access/src/main/java/ch/qos/logback/access/PatternLayout.java
==============================================================================
--- logback/trunk/logback-access/src/main/java/ch/qos/logback/access/PatternLayout.java (original)
+++ logback/trunk/logback-access/src/main/java/ch/qos/logback/access/PatternLayout.java Tue Oct 10 22:32:15 2006
@@ -107,6 +107,14 @@
* </td>
* </tr>
* <tr>
+ * <td align="center"><b>l</b></td>
+ * <td>
+ * <p>Remote user. In logback-access, this converter always returns
+ * the value "-".
+ * </p>
+ * </td>
+ * </tr>
+ * <tr>
* <td align="center"><b>m / requestMethod</b></td>
* <td>
* <p>
Modified: logback/trunk/logback-site/src/site/xdocTemplates/accessLogJetty.xml
==============================================================================
--- logback/trunk/logback-site/src/site/xdocTemplates/accessLogJetty.xml (original)
+++ logback/trunk/logback-site/src/site/xdocTemplates/accessLogJetty.xml Tue Oct 10 22:32:15 2006
@@ -18,25 +18,19 @@
<table>
<tr>
<td valign="top" align="top">
- <a rel="license"
- href="http://creativecommons.org/licenses/by-nc-nd/2.5/">
- <img alt="Creative Commons License" border="0"
- valign="top" align="top"
- src="http://creativecommons.org/images/public/somerights20.png" />
- </a>
+ <a rel="license" href="http://creativecommons.org/licenses/by/2.5/">
+ <img alt="Creative Commons License" style="border-width: 0"
+ src="http://creativecommons.org/images/public/somerights20.png"/>
+ </a>
+
</td>
<td>
- <p>Copyright © 2000-2006, QOS.ch</p>
+ <p>Copyright © 2005-2006, QOS.ch</p>
<p>
- This work is licensed under a
- <a rel="license"
- href="http://creativecommons.org/licenses/by-nc-nd/2.5/">
- Creative Commons
- Attribution-Noncommercial-No Derivative
- Works 2.5 License
- </a>
- .
+ This work is licensed under a <a rel="license"
+ href="http://creativecommons.org/licenses/by/2.5/">Creative
+ Commons Attribution 2.5 License</a>.
</p>
</td>
</tr>
@@ -45,50 +39,58 @@
<h2>Introduction</h2>
<p>
- Since its first design drafts, logback has been concieved as a modular framework.
- Being able to use logback's internal core in many situations, without heavy coding or
- complex specific configuration was one of our goals.
+ Logback was designed as a modular framework from the start. Being
+ able to use logback's internal core in many situations, without
+ heavy coding or complex specific configuration was one of our
+ goals.
</p>
+
<p>
- Lobgack access integrates with Servlet containers such as Jetty and Tomcat to provide
- HTTP-access log functionality.
+ Lobgack access integrates with Servlet containers such as Jetty
+ and Tomcat to provide HTTP-access log functionality.
</p>
<p>
- Integrating logback into Jetty is very simple. Once done, one can benefit from the power
- and flexibility found only in fully-fledged logging systems.
+ Integrating logback into Jetty is rather simple. Once done, you
+ can benefit from the power and flexibility found only in
+ fully-fledged logging systems.
</p>
<p>
- To use logback access with Jetty, first download the files, then place the
- <em>logback-core-VERSION.jar</em> and <em>logback-access-VERSION.jar</em> files
- in the Jetty classpath.
+ To use logback-access with Jetty, after downlading the logback
+ distribution, place the files <em>logback-core-VERSION.jar</em>
+ and <em>logback-access-VERSION.jar</em> under $JETTY_HOME/lib
+ directory, where $JETTY_HOME is the folder where you have
+ installed Jetty. We tested logback-access module with Jetty
+ version 6.0.1.
</p>
<h2>Logback's RequestLog implementation</h2>
<p>
- Logback's <code>ch.qos.logback.access.jetty.RequestLogImpl</code> is an
- implementation of jetty's <code>RequestLog</code> interface. This interface
- is used by Jetty to allow external components to manage request logging.
+ The <code>ch.qos.logback.access.jetty.RequestLogImpl</code>
+ class implements jetty's <code><a
+ href="http://jetty.mortbay.org/apidocs/org/mortbay/jetty/RequestLog.html">RequestLog</a></code>
+ interface. This interface is used by Jetty to allow external
+ components to manage request logging.
</p>
+ <!--
<p>
- <code>RequestLogImpl</code> can be seen as logback classic's
+ Our <code>RequestLogImpl</code> can be seen as logback classic's
<a href="http://logback.qos.ch/apidocs/ch/qos/logback/classic/LoggerContext.html">
<code>LoggerContext</code></a>. It is the central component of the logging
environnement.
</p>
+ -->
<p>
In logback, logging destinations are called Appenders. These classes
can be attached directly to <code>RequestLogImpl</code>.
</p>
- <p>Logback's internal error reporting system is based on Status objects.
- <code>RequestLogImpl</code> uses the same <code>StatusManager</code>
- as <code>LoggerContext</code> does.
- </p>
+
+
<p>
- To configure jetty in order to use <code>RequestLogImpl</code>, the
- following lines must be added to the jetty configuration
- file, namely <em>etc/jetty.xml</em>:
+ To configure jetty in order to use logback's
+ <code>RequestLogImpl</code>, add the following lines
+ to the jetty configuration file, namely <em>$JETTY_HOME/etc/jetty.xml</em>:
</p>
<pre>
<Ref id="requestLog">
@@ -104,24 +106,26 @@
the actual class that will be called at each logging request.
</p>
<p>
- By default, <code>RequestLogImpl</code> looks for a logback configuration
- file called <em>logback.xml</em>, in the same folder where jetty.xml
- is located, that is <em>etc/logback.xml</em>. This configuration file
- contains declarations of logback components. There, one can specify,
- at runtime, the destinations where the logging requests will be sent,
- and the format that logback will use to display the logging events.
+ By default, <code>RequestLogImpl</code> looks for a logback
+ configuration file called <em>logback-access.xml</em>, in the
+ same folder where <em>jetty.xml</em> is located. This
+ configuration file contains directives for configuring logback
+ components. Among others, you can specify the appenders where
+ the logging requests will be sent, and their format.
</p>
- <p> The logback.xml file
- is slightly different than the usual logback classic
- configuration file. Most of it is the same: Appenders and
- Layouts (which are logback components to format logging output)
- are declared the exact same way. However, loggers
- elements are not allowed.
+
+ <p>Altough similar, the <em>logback-access.xml</em> file is slightly
+ different than the usual logback classic configuration file.
+ Appenders and Layouts are declared the exact same way. However, in
+ the access module there is no notion of loggers and consequently
+ loggers elements are disallowed in configuraiton files for
+ logback-access.
</p>
- <p> It is possible to put the logback
- configuration file anywhere, as long as it's path is
- specified. Here is another example of declaration of the logback
- component in the jetty configuration file, with a path to the logback.xml file.
+
+ <p>As long the path is specified, you can place the logback
+ configuration file in other location. Here is another example of
+ jetty configuration file, with a path to the logback access
+ configuration file.
</p>
<pre>
<Ref id="requestLog">
@@ -129,13 +133,15 @@
<New id="requestLogImpl"
class="ch.qos.logback.access.jetty.RequestLogImpl">
</New>
- <Set name="fileName">path/to/logback.xml</Set>
+ <Set name="fileName">path/to/myaccess.xml</Set>
</Set>
</Ref>
</pre>
+
+ <h2>Example 1: logback-access configuration</h2>
<p>
- Here is a sample logback.xml file that can be used right
- away:
+ Here is a sample <em>logback-access.xml</em> file that you can
+ immediately put to use:
</p>
<pre>
<configuration>
@@ -143,8 +149,7 @@
class="ch.qos.logback.core.ConsoleAppender">
<layout
class="ch.qos.logback.access.PatternLayout">
- <param name="Pattern"
- value="%date %server %remoteIP %clientHost %user %requestURL" />
+ <Pattern>%h %l %u %user %date "%r" %s %b</Pattern>
</layout>
</appender>
@@ -152,12 +157,45 @@
</configuration>
</pre>
<p>
- This file declares a logging destination (in the <em>appender</em> element). The
- appender used is the ConsoleAppender which obviously logs events to the console.
- A PatternLayout is also declared, to format the output. More informations about this
- layout later on in this document.
+ It declares a <code>ConsoleAppender</code> which directs its
+ output at the console. The <code>ConsoleAppender</code> contains
+ a <code>PatternLayout</code> format the output. The log format is
+ specied using the %h %l %u %user %date "%r" %s %b" pattern which
+ is the Commong Log Format (CLF). This format is recognized by log
+ analysers such as <a href="http://www.analog.cx/">Analog</a> or <a
+ href="http://awstats.sourceforge.net/">AWStats</a>.
</p>
- <p>Another configuration file, using logback access <code>SMTPAppender</code>, could be:</p>
+
+ <p>Instead of specifying the complete pattern, the word "common"
+ or "clf" can be used as a shorthand. Thus, the following are all
+ equivalent
+ </p>
+
+ <div class="source"><Pattern>%h %l %u %user %date "%r" %s %b</Pattern>
+<Pattern>common</Pattern>
+<Pattern>clf</Pattern></div>
+
+ <p>The so called "combined" format is also widely recognized. It is
+ defined as the '%h %l %u %t "%r" %s %b "%i{Referer}"
+ "%i{User-Agent}"' pattern. As a facilitator, you can use the
+ "combined" as a shorthand. Thus, the following directive
+ </p>
+
+ <div class="source"><layout class="ch.qos.logback.access.PatternLayout">
+ <Pattern>%h %l %u %t "%r" %s %b "%i{Referer}" "%i{User-Agent}"</Pattern>
+ </layout></div>
+
+ <p>is equivalent to:</p>
+
+ <div class="source"><layout class="ch.qos.logback.access.PatternLayout">
+ <Pattern>combined</Pattern></layout>
+ </div>
+
+
+ <h2>Example 2: RollingFileAppender</h2>
+
+ <p>In the next configuration file, using logback access
+ <code>SMTPAppender</code>, could be:</p>
<pre>
<configuration>
<appender name="SMTP"
@@ -176,35 +214,40 @@
<appender-ref ref="SMTP" />
</configuration>
</pre>
+
+
<p>
- Here, there is no output to the console. Instead, logback access builds a buffer with
- the logging events, and in case of an events that meets a certain condition,
- an email is sent to the specified address, using the declared informations.
- By default, an event that would cause an email to be sent is when a status
- code of 500 or more occurs, which means that an error occured on the server.
- </p>
- <p>
- These two configuration example should give you an idea of the
- existing possibilities when having at hand the flexibility of a logging framework
- like logback. Most of the things that you can do with the classic module of logback is
- available for access logging.
- </p>
- <p>
- A special, module-specific implementation of <code>PatternLayout</code>
- was implemented to allow http-specific patterns to be used.
- The <a href="http://logback.qos.ch/apidocs/ch/qos/logback/access/PatternLayout.html">
- <code>ch.qos.logback.access.PatternLayout</code></a> provides a way to
- format the logging output that is just as easy and flexible
- as the usual <code>PatternLayout</code>.
- </p>
- <p>
- For more information about the
- general use of a <code>PatternLayout</code>, please refer to logback
- classic's <a href="http://logback.qos.ch/apidocs/ch/qos/logback/classic/PatternLayout.html">
- <code>ch.qos.logback.classic.PatternLayout</code></a>.
+ Here, there is no output to the console. Instead, logback access
+ builds a buffer with the logging events, and in case of an
+ events that meets a certain condition, an email is sent to the
+ specified address, using the declared informations. By default,
+ an event that would cause an email to be sent is when a status
+ code of 500 or more occurs, which means that an error occured on
+ the server.
+ </p>
+
+ <p>
+ These two configuration examples should give you an idea of the
+ possibilities offered by the logback-access module. In
+ principle, most of the things that you can do with
+ logback-classic module are equally possible with logback-access.
</p>
+
+ <h2>PatternLayout</h2>
+
<p>
- Logback access <code>PatternLayout</code> offers the following possibilities:
+ An http-specific implementation of <code>PatternLayout</code> is
+ included in the access module. The <a
+ href="http://logback.qos.ch/apidocs/ch/qos/logback/access/PatternLayout.html">
+ <code>ch.qos.logback.access.PatternLayout</code></a> provides a
+ way to format the logging output that is just as easy and
+ flexible as the <code>PatternLayout</code> found in logback
+ classic.
+ </p>
+
+ <p>
+ Logback access <code>PatternLayout</code> offers the following
+ possibilities:
</p>
<table border="1" CELLPADDING="8">
<th align="center">Conversion Character or Word</th>
@@ -250,6 +293,16 @@
</p>
</td>
</tr>
+ <tr>
+ <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>
<td align="center"><b>reqParameter</b></td>
<td>
@@ -361,5 +414,21 @@
</td>
</tr>
</table>
+
+
+ <!--
+ <p>
+ For more information about the
+ <code>PatternLayout</code>, please refer to chapter 5 of the user manual.
+ </p>
+ -->
+ <!--
+
+ <h2>Troubleshooring</h2>
+ <p>Logback's internal error reporting system is based on Status objects.
+ <code>RequestLogImpl</code> uses the same <code>StatusManager</code>
+ as <code>LoggerContext</code> does.
+ </p>
+ -->
</body>
</document>
More information about the logback-dev
mailing list