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>