k.logback-site.0.7.source-code.access.xml Maven / Gradle / Ivy
<document>
<!--
Warning: do not use any auto-format function on this file.
Since "source" divs use pre as white-space, it affects the
look of the code parts in this document.
-->
<body>
<h2>Access log with logback and Jetty</h2>
<div class="author">
Authors: Ceki Gülcü, Sébastien Pennec
</div>
<table>
<tr>
<td valign="top" align="top">
<a rel="license"
href="http://creativecommons.org/licenses/by-nc-sa/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>
<!--Creative Commons License-->
This work is licensed under a
<a rel="license"
href="http://creativecommons.org/licenses/by-nc-sa/2.5/">
Creative Commons
Attribution-NonCommercial-ShareAlike 2.5
License
</a>
.
<!--/Creative Commons License-->
</p>
</td>
</tr>
</table>
<h2>Introduction</h2>
<p>
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.
</p>
<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.
</p>
<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
version 6.0.1.
</p>
<h2>Logback's RequestLog implementation</h2>
<p>
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>
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>
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>
<div class="source"><pre><Ref id="requestLog">
<Set name="requestLog">
<New id="requestLogImpl"
class="ch.qos.logback.access.jetty.RequestLogImpl">
</New>
</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 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>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
jetty configuration file, with a path to the logback access
configuration file.
</p>
<div class="source"><pre><Ref id="requestLog">
<Set name="requestLog">
<New id="requestLogImpl"
class="ch.qos.logback.access.jetty.RequestLogImpl">
</New>
<Set name="fileName">path/to/myaccess.xml</Set>
</Set>
</Ref></pre></div>
<h2>Example 1: logback-access configuration</h2>
<p>
Here is a sample <em>logback-access.xml</em> file that you can
immediately put to use:
</p>
<div class="source"><pre><configuration>
<appender name="STDOUT"
class="ch.qos.logback.core.ConsoleAppender">
<layout
class="ch.qos.logback.access.PatternLayout">
<Pattern>%h %l %u %user %date "%r" %s %b</Pattern>
</layout>
</appender>
<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>.
</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"><pre><Pattern>%h %l %u %user %date "%r" %s %b</Pattern>
<Pattern>common</Pattern>
<Pattern>clf</Pattern></pre></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"><pre><layout class="ch.qos.logback.access.PatternLayout">
<Pattern>%h %l %u %t "%r" %s %b "%i{Referer}" "%i{User-Agent}"</Pattern>
</layout></pre></div>
<p>is equivalent to:</p>
<div class="source"><pre><layout class="ch.qos.logback.access.PatternLayout">
<Pattern>combined</Pattern>
</layout></pre></div>
<h2>Example 2: RollingFileAppender</h2>
<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">
<rollingPolicy
class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
<ActiveFileName>access.log"</ActiveFileName>
<FileNamePattern>access.%d{yyyy-MM-dd}.log.zip</FileNamePattern>
</rollingPolicy>
<layout class="ch.qos.logback.access.PatternLayout">
<Pattern">combined</Pattern">
</layout>
</appender>
<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>
<h2>PatternLayout</h2>
<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">
<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>
<th align="center">Effect</th>
<tr>
<td align="center"><b>a / remoteIP</b></td>
<td>
<p>
Remote IP address.
</p>
</td>
</tr>
<tr>
<td align="center"><b>A / localIP</b></td>
<td>
<p>
Local IP address.
</p>
</td>
</tr>
<tr>
<td align="center"><b>b / B / byteSent</b></td>
<td>
<p>
Response's content length.
</p>
</td>
</tr>
<tr>
<td align="center"><b>h / clientHost</b></td>
<td>
<p>
Remote host.
</p>
</td>
</tr>
<tr>
<td align="center"><b>H / protocol</b></td>
<td>
<p>
Request protocol.
</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{paramName}</b></td>
<td>
<p>
Parameter of the response. This conversion word can be followed by a key
whose corresponding data will be extracted from the header information.
</p>
</td>
</tr>
<tr>
<td align="center"><b>i{header} / header{header}</b></td>
<td>
<p>
Request header. Just like the reqParameter
conversion word, reqParameter can be followed by a key.
</p>
</td>
</tr>
<tr>
<td align="center"><b>m / requestMethod</b></td>
<td>
<p>
Request method.
</p>
</td>
</tr>
<tr>
<td align="center"><b>r / requestURL</b></td>
<td>
<p>
URL requested.
</p>
</td>
</tr>
<tr>
<td align="center"><b>s / statusCode</b></td>
<td>
<p>
Status code of the request.
</p>
</td>
</tr>
<tr>
<td align="center"><b>t / date</b></td>
<td>
<p>
Date of the event.
</p>
</td>
</tr>
<tr>
<td align="center"><b>u / user</b></td>
<td>
<p>
Remote user.
</p>
</td>
</tr>
<tr>
<td align="center"><b>U / requestURI</b></td>
<td>
<p>
Requested URI.
</p>
</td>
</tr>
<tr>
<td align="center"><b>v / server</b></td>
<td>
<p>
Server name.
</p>
</td>
</tr>
<tr>
<td align="center"><b>localPort</b></td>
<td>
<p>
Local port.
</p>
</td>
</tr>
<tr>
<td align="center"><b>reqAttribute{attributeName}</b></td>
<td>
<p>
Attribute of the request. Just like the reqParameter
conversion word, reqAttribute can be followed by a key.
</p>
</td>
</tr>
<tr>
<td align="center"><b>reqCookie{cookie}</b></td>
<td>
<p>
Request cookie. Just like the reqParameter
conversion word, reqCookie can be followed by a key.
</p>
</td>
</tr>
<tr>
<td align="center"><b>responseHeader{header}</b></td>
<td>
<p>
Header of the response. Just like the reqParameter
conversion word, responseHeader can be followed by a key.
</p>
</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>
© 2015 - 2025 Weber Informatics LLC | Privacy Policy