Author: seb Date: Tue Dec 19 14:25:09 2006 New Revision: 1117 Modified: logback/trunk/logback-site/src/site/xdocTemplates/access.xml Log: documentation update: Access.xml updated to include tomcat info, + jmx components configuration Modified: logback/trunk/logback-site/src/site/xdocTemplates/access.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/access.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/access.xml Tue Dec 19 14:25:09 2006 @@ -9,7 +9,7 @@ <body> - <h2>Access log with logback and Jetty</h2> + <h2>Access log with logback, Jetty and Tomcat</h2> <div class="author"> Authors: Ceki Gülcü, Sébastien Pennec </div> @@ -58,38 +58,73 @@ Lobgack access integrates with Servlet containers such as Jetty and Tomcat to provide HTTP-access log functionality. </p> + + <h2>Logback Access and Tomcat</h2> + + <p> + To use logback-access with Tomcat, after downlading the logback + distribution, place the files <em>logback-core-VERSION.jar</em> + and <em>logback-access-VERSION.jar</em> under $TOMCAT_HOME/common/lib + directory, where $TOMCAT_HOME is the folder where you have + installed Tomcat. We have tested logback-access module with Tomcat + version 5.5.20. + </p> + + <h3>LogbackValve</h3> + + <p> + The <a href="xref/ch/qos/logback/access/tomcat/LogbackValve.html"> + <code>ch.qos.logback.access.tomcat.LogbackValve</code></a> + class extends Tomcat's <code><a + href="http://tomcat.apache.org/tomcat-5.5-doc/catalina/docs/api/org/apache/catalina/valves/ValveBase.html"> + ValveBase</a></code> + class. This class is used to allow external + components to be integrated into Tomcat. + </p> + + <p> + To configure Tomcat in order to use + <code>LogbackValve</code>, add the following lines + to the tomcat server configuration file, namely <em>$TOMCAT_HOME/conf/server.xml</em>: + </p> + <div class="source"><pre><Valve className="ch.qos.logback.access.tomcat.LogbackValve"/></pre></div> <p> - Integrating logback into Jetty is rather simple. Once done, you - can benefit from the power and flexibility found only in - fully-fledged logging systems. + This line need to be nested in an <em>Engine</em> element. </p> + <p> + By default, <code>LogbackValve</code> looks for a logback + configuration file called <em>logback-access.xml</em>, in the + same folder where <em>server.xml</em> is located, that is + in <em>$TOMCAT_HOME/conf/</em>. 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. Please refer + to the above description about logback access and Jetty for examples + of configuration. + </p> + <h2>Logback Access and Jetty</h2> + <p> 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 + installed Jetty. We have tested logback-access module with Jetty version 6.0.1. </p> - <h2>Logback's RequestLog implementation</h2> + <h3>Logback's RequestLog implementation</h3> <p> - The <code>ch.qos.logback.access.jetty.RequestLogImpl</code> + The <a href="xref/ch/qos/logback/access/jetty/RequestLogImpl.html"> + <code>ch.qos.logback.access.jetty.RequestLogImpl</code></a> 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> - 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>. @@ -120,17 +155,9 @@ components. Among others, you can specify the appenders where the logging requests will be sent, and their format. </p> - - <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>As long the path is specified, you can place the logback - configuration file in other location. Here is another example of + + <p>As long the path is specified, you can place the logback + configuration file in any location. Here is another example of jetty configuration file, with a path to the logback access configuration file. </p> @@ -143,7 +170,17 @@ </Set> </Ref></pre></div> - <h2>Example 1: logback-access configuration</h2> + <h2>Logback Access Configuration</h2> + + <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> + + <h3>Example 1: basic logback-access configuration</h3> <p> Here is a sample <em>logback-access.xml</em> file that you can immediately put to use: @@ -195,16 +232,16 @@ </layout></pre></div> - <h2>Example 2: RollingFileAppender</h2> + <h3>Example 2: RollingFileAppender</h3> <p>Another configuration file, using logback' <code>RollingFileAppender</code>, could be:</p> <div class="source"><pre><configuration> <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> + <File>access.log"</File> <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> - <ActiveFileName>access.log"</ActiveFileName> <FileNamePattern>access.%d{yyyy-MM-dd}.log.zip</FileNamePattern> </rollingPolicy> @@ -232,12 +269,12 @@ logback-classic module are equally possible with logback-access. </p> - <h2>PatternLayout</h2> + <h3>PatternLayout</h3> <p> 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"> + href="xref/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 @@ -412,21 +449,158 @@ </td> </tr> </table> + + <h2>JMX Components</h2> + + <p>Logback access easily integrates with JMX servers to publish useful information + about some of its components. + </p> + + <p> + Both <code>RequestLogImpl</code> and <code>LogbackValve</code> can be + published and modified via JMX. A special filter, that we will cover + further down this document, publishes statistical views of access logs. + </p> + + + <h3>Configuring Tomcat</h3> + + <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 access + with JConsole by issuing the following command in a shell: + </p> +<div class="source"><pre>jconsole &</pre></div> - <!-- - <p> - For more information about the - <code>PatternLayout</code>, please refer to chapter 5 of the user manual. - </p> - --> - <!-- + <p> + The user might prefer to access her components thanks to 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> + + <p>Then, add the following lines to the + <em>$TOMCAT_HOME/bin/catalina.sh</em> configuration file: + </p> + +<div class="source"><pre><!-- at the beginning of the file --> +CATALINA_OPTS="-Dcom.sun.management.jmxremote" +CATALINA_OPTS="$CATALINA_OPTS -Djavax.management.builder.initial=mx4j.server.MX4JMBeanServerBuilder" + +<!-- in the "Add on extra jar files to CLASSPATH" section --> +CLASSPATH="$CLASSPATH":"$CATALINA_HOME"/bin/mx4j-impl.jar</pre></div> + + <p> + Finally, declare a new <code>Connector</code> in the + <em>$TOMCAT_HOME/conf/server.xml</em> file: + </p> + +<div class="source"><pre><Connector port="8050" + handler.list="mx" + mx.enabled="true" + mx.httpHost="localhost" + 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> + +<div class="source"><pre>http://host_name:8082/</pre></div> + + <h3>Configuring Jetty</h3> + + <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"/> +<!-- initialize the Jetty MBean container --> +<Get id="Container" name="container"> + <Call name="addEventListener"> + <Arg> + <New class="org.mortbay.management.MBeanContainer"> + <Arg><Ref id="MBeanServer"/></Arg> + <Set name="managementPort">8082</Set> + <Call name="start" /> + </New> + </Arg> + </Call> +</Get></pre></div> + + <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> + + <p> + Logback's <code>RequestLogImpl</code> is available, and its <code>start()</code> + and <code>stop()</code> method can be called. + </p> + + + <h3>CountingFilter</h3> + + <p> + Logback can provide a statistical view of the accesses to the server. This is done by using the + <a href="xref/ch/qos/logback/access/filter/CountingFilter.html"><code>CountingFilter</code></a> class. + </p> + + <p> + To use the <code>CountingFilter</code>, one just needs to declare it, like any + other filter: + </p> + +<div class="source"><pre><configuration> + <b><filter class="ch.qos.logback.access.filter.CountingFilter"> + <name>countingFilter</name> + </filter></b> + + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.access.PatternLayout"> + <Pattern>%h %l %u %t \"%r\" %s %b</Pattern> + </layout> + </appender> + + <appender-ref ref="STDOUT" /> +</configuration></pre></div> + + <p> + This component registers itself to the JMX server and publishes + the following statistical figures: + </p> + + <ul> + <p>Minute average</p> + <p>Last minute's count</p> + <p>Hourly average</p> + <p>Last hour's count</p> + <p>Daily average</p> + <p>Last day's count</p> + <p>Weekly average</p> + <p>Last week's count</p> + <p>Monthly average</p> + <p>Last month's count</p> + <p>Total accesses</p> + </ul> - <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>