[logback-dev] svn commit: r1478 - logback/trunk/logback-site/src/site/pages
noreply.ceki at qos.ch
noreply.ceki at qos.ch
Wed Mar 28 21:01:34 CEST 2007
Author: ceki
Date: Wed Mar 28 21:01:34 2007
New Revision: 1478
Modified:
logback/trunk/logback-site/src/site/pages/access.html
logback/trunk/logback-site/src/site/pages/news.html
Log:
doc updates
Modified: logback/trunk/logback-site/src/site/pages/access.html
==============================================================================
--- logback/trunk/logback-site/src/site/pages/access.html (original)
+++ logback/trunk/logback-site/src/site/pages/access.html Wed Mar 28 21:01:34 2007
@@ -30,86 +30,88 @@
<h1>Introduction</h1>
<p>Logback was designed as a modular framework from the
- start. Making logback-core reusable under different
- circumstances, without too much coding was one of our main
- goals. As such, logback-access builds on top of logback-core. It
- fully integrates with Servlet containers such as Jetty or Tomcat
- to provide HTTP-access log functionality.
+ start. Making logback-core reusable under different circumstances,
+ without much recoding was one of our main goals. As such,
+ logback-access builds on top of logback-core. It fully integrates
+ with Servlet containers such as Jetty or Tomcat to provide
+ HTTP-access log functionality.
</p>
<a name="tomcat"></a>
- <h2>Logback Access and Tomcat</h2>
+ <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/server/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>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/server/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.
+ 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>:
+ 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>This line need to be nested in an <em>Engine</em> element.
+ <p>This line is usually nested within 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 description below
- about logback access configuration for examples.
+ <p>By default, <code>LogbackValve</code> looks for a 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-access components. It is used
+ to specify appenders where the logging requests will be their
+ format, and filters. Please refer to the <a
+ href="#configuration">section discussing</a> this subject further
+ below.
</p>
<a name="jetty"></a>
- <h2>Logback Access and Jetty</h2>
+ <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 have tested logback-access module with Jetty
- version 6.0.1.
+ <p>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 have tested logback-access module with Jetty
+ version 6.0 as well as 6.1.
</p>
- <h3>Logback's RequestLog implementation</h3>
+ <h3>Logback's implementation of
+ <code>org.mortbay.jetty.RequestLog</code> interface</h3>
<p>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.
+ 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. Jetty delegates the manament of access logging
+ functionality to implementations of this interface.
</p>
- <p>In logback, logging destinations are called Appenders. These
- classes can be attached directly to <code>RequestLogImpl</code>.
+ <p>In logback, a logging destination is called an "appender" which
+ can be directly attached to a
+ <code>ch.qos.logback.access.jetty.RequestLogImpl</code> instance.
</p>
- <p>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>In order to configure Jetty to use logback-access's
+ <code>RequestLogImpl</code>, please add the following lines to
+ jetty's main configuration file, namely
+ <em>$JETTY_HOME/etc/jetty.xml</em>:
</p>
<div class="source"><pre><Ref id="requestLog">
<Set name="requestLog">
@@ -119,11 +121,6 @@
</Set>
</Ref></pre></div>
- <p>These lines reference the requestLog functionnality of Jetty,
- setting 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-access.xml</em>, in the same
folder where <em>jetty.xml</em> is located. This configuration
@@ -134,8 +131,8 @@
<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.
+ jetty configuration file, including the path to the
+ <em>logback-access.xml</em> configuration file.
</p>
<div class="source"><pre><Ref id="requestLog">
@@ -147,20 +144,21 @@
</Set>
</Ref></pre></div>
- <h2>Logback Access Configuration</h2>
+ <a name="configuration"></a>
+ <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.
+ different than its more common counterpart in logback-classic.
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.
+ logger elements are disallowed in logback-access configuraiton
+ files.
</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:
+ Here is a small but fully functional <em>logback-access.xml</em>
+ configuration file:
</p>
<div class="source"><pre><configuration>
<appender name="STDOUT"
@@ -174,18 +172,18 @@
<appender-ref ref="STDOUT" />
</configuration></pre></div>
<p>
- 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>.
+ It declares a <code>ConsoleAppender</code> which prints its output
+ on the console. The <code>ConsoleAppender</code> contains a
+ <code>PatternLayout</code> object responsible to format this
+ output. The log format is specied by the "%h %l %u %user %date
+ "%r" %s %b" pattern which incidentally corresponds to Common 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>Instead of specifying the complete pattern, the word "common"
- or "clf" can be used as a shorthand. Thus, the following are all
- equivalent
+ <p>The words "common" or "clf" are interpreted as shorthands for
+ the said pattern. Thus, the following are all equivalent:
</p>
<div class="source"><pre><Pattern>%h %l %u %user %date "%r" %s %b</Pattern>
@@ -211,8 +209,13 @@
<h3>Example 2: RollingFileAppender</h3>
- <p>Another configuration file, using logback'
- <code>RollingFileAppender</code>, could be:</p>
+ <p>The configuration file below configures a daily rolling
+ <code>RollingFileAppender</code>. Note that due to the
+ <em>.zip</em> suffix included in the value for <span
+ class="option">FileNamePattern</span> option, the log file are not
+ only rolled daily, but they are also automatically compressed.</p>
+
+
<div class="source"><pre><configuration>
<appender name="FILE"
class="ch.qos.logback.core.rolling.RollingFileAppender">
@@ -229,86 +232,61 @@
<appender-ref ref="FILE" />
</configuration></pre></div>
-
- <p>
- Here, there is no output to the console. Instead, logback access
- logs to the file named access.log. This file will be rolled over
- every 24 hours. We specify in the configuration the name of the file
- where the actual logging is added, and the pattern that the archived
- files must match.
- The newly archived file will be automatically compressed.
- </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>These two examples should give you an idea of the possibilities
+ offered by logback-access. In principle, most if not all of the
+ features available in logback-classic are also available in
+ logback-access.
</p>
<h3>PatternLayout</h3>
- <p>
- An http-specific implementation of <code>PatternLayout</code> is
- included in the access module. The <a
- 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
- classic.
- </p>
-
- <p>
- For detailled instructions on how to use the <code>PatternLayout</code> for
- logback access, please refer to the
- <a href="manual/layouts.html#AccessPatternLayout">corresponding chapter</a>
- of the logback manual.
+ <p>Logback-access ships with an http-specific implementation of <a
+ href="xref/ch/qos/logback/access/PatternLayout.html">
+ <code>PatternLayout</code></a>. For detailled instructions on how
+ to use the <code>PatternLayout</code>, please refer to the <a
+ href="manual/layouts.html#AccessPatternLayout">corresponding
+ chapter</a> of the logback manual.
</p>
<h2>JMX Components</h2>
- <p>Logback access easily integrates with JMX servers to publish useful information
- about some of its components.
+ <p>Logback-access integrates with JMX servers to publish
+ information about 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>Both <code>RequestLogImpl</code> and <code>LogbackValve</code>
+ expose data and can be updated via JMX. A special filter, covered
+ further down this document, publishes statistical data on access
+ logs.
</p>
- <h3>Configuring Tomcat</h3>
+ <h3>Configuring Tomcat for JMX</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>In order to configure Tomcat for JMX, please add the following
+ lines to the <em>$TOMCAT_HOME/bin/catalina.sh</em> shell script
+ (or its MS Windows equivalent):
</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>
-<div class="source"><pre>jconsole &</pre></div>
-
- <p>
- The user might prefer to access her 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>
-
- <p>Then, add the following lines to the
- <em>$TOMCAT_HOME/bin/catalina.sh</em> configuration file:
+ <p>After you launch Tomcat, you can access the MBeans exposed by
+ Tomcat throught he JConsole application, which can be started with
+ the following command:
+ </p>
+<div class="source"><pre>jconsole</pre></div>
+
+ <p>If you prefer MX4J to access your components via a web-based
+ interface, here is a short summary of the steps to follow. After
+ <a href="http://mx4j.sourceforge.net/">downloading 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> file in the
+ <em>$TOMCAT_HOME/common/lib/</em> directory. Once that is done,
+ add the following lines to the
+ <em>$TOMCAT_HOME/bin/catalina.sh</em> shell script:
</p>
<div class="source"><pre><!-- at the beginning of the file -->
@@ -331,11 +309,11 @@
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:
+ Once Tomcat is started, you should be able to reach your JMX
+ components by pointing your browser at the following URL:
</p>
-<div class="source"><pre>http://host_name:8082/</pre></div>
+<div class="source"><pre>http://localhost:8082/</pre></div>
<h3>Configuring Jetty</h3>
@@ -359,28 +337,27 @@
</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:
</p>
-<div class="source"><pre>http://host_name:8082/</pre></div>
+<div class="source"><pre>http://localhost: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>Logback-access' <code>RequestLogImpl</code> should be
+ available, including its <code>start()</code> and
+ <code>stop()</code> methods.
</p>
- <h3>CountingFilter</h3>
+ <h2><code>CountingFilter</code></h2>
- <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>With the help of <a
+ href="xref/ch/qos/logback/access/filter/CountingFilter.html"><code>CountingFilter</code></a>
+ class, logback-access can provide statistical data about access to
+ the web-server.
</p>
- <p>
- To use the <code>CountingFilter</code>, one just needs to declare it, like any
- other filter:
+ <p>If you wish to make use of <code>CountingFilter</code>, you to
+ declare it, as any other filter:
</p>
<div class="source"><pre><configuration>
@@ -400,22 +377,68 @@
<p>
This component registers itself to the JMX server and publishes
- the following statistical figures:
+ the statistical data such as averages by minute, by hour, by
+ day, by week, and by month. Last month's, week's, day's, hour's
+ and minute's counts as well as the total number of access are
+ also exposed.
</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><code>TeeFilter</code></h2>
+
+ <p>For debugging purposes, it is often handy to capture the client
+ request as well as the server response as is. The
+ <code>TeeFilter</code> was desgined precisely for this purpose.
+ </p>
+
+ <p>The <code>TeeFilter</code> is a regular servlet filter. Like other
+ servlet filters, it needs to be declared in your web-application's
+ <em>web.xml</em> file:
+</p>
+
+<div class="source"><filter>
+ <filter-name>TeeFilter</filter-name>
+ <filter-class>ch.qos.logback.access.servlet.TeeFilter</filter-class>
+</filter>
+
+<filter-mapping>
+ <filter-name>TeeFilter</filter-name>
+ <url-pattern>/*</url-pattern>
+</filter-mapping>
+</div>
+
+ <p>We have tested <code>TeeFilter</code> to the best of our
+ ability. However, since it duplicates the input stream of the
+ request and the output stream of the response, it may interfere with
+ your application. For large input or output, it will add masurable
+ latency. Although we have already fixed all currently known bugs,
+ <code>TeeFilter</code> has broken otherwise correctly behaving
+ applications. Thus, in case of doubt, do not hesitate to disabl
+ <code>TeeFilter</code>.
+
+ </p>
+
+ <p>Once <code>TeeFilter</code> is installed, the <a
+ href="manual/layouts.html#AccessPatternLayout">PatternLayout </a>
+ converters <code>fullRequest</code> and <code>fullResponse</code>
+ will output the full contents of the request and respectively the
+ response.
+ </p>
+
+ <p>Here is a sample logback-access.xml configuration file which will
+ output the full contents of the request and response on the console.
+ </p>
+<div class="source"><configuration>
+ <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+ <layout class="ch.qos.logback.access.PatternLayout">
+ <Pattern>%fullRequest%n%n%fullResponse</Pattern>
+ </layout>
+ </appender>
+
+ <appender-ref ref="STDOUT" />
+</configuration>
+</div>
+
<script src="templates/footer.js"></script>
</div>
</body>
Modified: logback/trunk/logback-site/src/site/pages/news.html
==============================================================================
--- logback/trunk/logback-site/src/site/pages/news.html (original)
+++ logback/trunk/logback-site/src/site/pages/news.html Wed Mar 28 21:01:34 2007
@@ -30,12 +30,14 @@
<h3>xxxx , 2007 - Release of version 0.9.4</h3>
- <p>Significant bug fixes made to <code>TeeFilter</code> and
- Co. located in the logback-access module. Images and other binary
- files are now intercepted and replayed correctly. As for
+ <p>Significant bug fixes made to
+ <code>c.q.l.access.TeeFilter</code> and Co. Images and other
+ binary files are now intercepted and replayed correctly. As for
"x-www-form-urlencoded" post requests, their input buffer is left
- untouched. In a best-effort attempt, the input buffer is later
- reconstructed. However, it may differ from the original.
+ untouched. In a best-effort attempt, the input buffer for
+ "x-www-form-urlencoded" post requests is later reconstructed
+ through the request parameters. However, it may differ from the
+ original buffer.
</p>
<h3>March 20th, 2007 - Release of version 0.9.3</h3>
More information about the logback-dev
mailing list