[logback-dev] svn commit: r1117 - logback/trunk/logback-site/src/site/xdocTemplates
noreply.seb at qos.ch
noreply.seb at qos.ch
Tue Dec 19 14:25:09 CET 2006
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>
More information about the logback-dev
mailing list