<br>
<table cellpadding="0" cellspacing="8" border="0" width="20%">
<tbody>
<tr>
<td valign="middle" bgcolor="#ccccff"><small><a href="Server.html">
BACK</a></small></td>
<td valign="middle" bgcolor="#ccccff"><small><a href="index.html">
INDEX</a></small></td>
<td valign="middle" bgcolor="#ccccff"><small><a href="..">
EXIT</a></small></td>
<td valign="middle" bgcolor="#ccccff"><small><a href="XmlConfiguration.html">
NEXT</a></small></td>
</tr>
</tbody>
</table>
<h1>Logging and Debugging </h1>
<p>
Jetty 4.x contains its own logging mechanism based on the org.mortbay.util.Log class. In Jetty 5.x, this
has been ported to commons logging, which allows a more flexible approach. This section describes the
various log streams and their configurations.
</p>
<h2>Request Logs</h2>
<p>
Request logs are a record of the requests that the server has processed. They create an entry for
each request received and are commonly in the standard NCSA format so they can analysed by tools
like <a href="http://www.mrunix.net/webalizer/">webalizer</a>. A standard request log entry includes
the client IP, date, method, URL, result, size, referrer and user agent. eg:
<pre>
123.4.5.6 - - [27/Aug/2004:10:16:17 +0000] \
"GET /jetty/tut/XmlConfiguration.html HTTP/1.1" \
200 76793 "http://localhost:8080/jetty/tut/logging.html" \
"Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.6) Gecko/20040614 Firefox/0.8"
</pre>
Jetty supports pluggable Request logs and any class that implements
<a href="/javadoc/org/mortbay/http/RequestLog.html">org.mortbay.http.RequestLog</a> may be plugged into
<a href="/javadoc/org/mortbay/http/HttpServer.html">HttpServer</a>
or
<a href="/javadoc/org/mortbay/http/HttpContext.html">HttpContext</a>. Jetty provides an
implementation called
<a href="/javadoc/org/mortbay/http/NCSARequestLog.html">NCSARequestLog</a>
which supports the NCSA format in files that can be rolled over on a daily basis.
</p>
<p>
To configure a request log for the whole server in jetty.xml:<pre>
<Set name="RequestLog">
<New class="org.mortbay.http.NCSARequestLog">
<Set name="filename"><SystemProperty name="jetty.home" default="."/>/logs/yyyy_mm_dd.request.log</Set>
<Set name="retainDays">90</Set>
<Set name="append">true</Set>
<Set name="extended">true</Set>
<Set name="LogTimeZone">GMT</Set>
<Set name="ignorePaths">
<Array type="String">
<Item>/images/*</Item>
<Item>*.css</Item>
</Array>
</Set>
</New>
</Set>
</pre>
This configures a request log in $JETTY_HOME/logs with filenames including the date. Old log files are
kept for 90 days before being deleted. Existing log files are appended to and the extended NCSA format
is used in the GMT timezone. Logs entries are not generated for requests in the path /images/* or
matching *.css.
</p>
<p>
A request log can be added to a single webapp or context as follows:<pre>
<Call name="addWebApplication">
<Arg>/my-example/*</Arg>
<Arg><./webapps/my-example.war</Arg>
<Set name="RequestLog">
<New class="org.mortbay.http.NCSARequestLog">
...
</New>
</Set>
</Call>
</pre>
A context request log can also be configured in a <code>jetty-web.xml</code> file in a similar way.
</p>
<h2>Implementation Log</h2>
<p>The implementation log is a stream of TRACE, DEBUG, INFO, WARN and ERROR messages from the Jetty
implementation. Jetty 5 uses <a href="http://jakarta.apache.org/commons/logging/">Jakarta Commons Logging</a>
with a
<a href="/javadoc/org/mortbay/log/package-summary.html">default logger</a>
based on the Jetty 4 log. In addition, commons logging allows for other log
implementations to be plugged in, including
<a href="http://logging.apache.org/log4j/docs/index.html">Log4J</a>, JDK 1.4, and
its own <a href="http://jakarta.apache.org/commons/logging/api/org/apache/commons/logging/impl/SimpleLog.html">SimpleLog</a>.
</p>
<h3>Jetty Log Implementation</h3>
<p>
The
<a href="/javadoc/org/mortbay/log/package-summary.html">Jetty log implementation</a> is made the default for commons logging in the start.config file, which
specifies org.apache.commons.logging.LogFactory=org.mortbay.log.Factory. The jetty log factory proves a
default log instance as well as optional named (by package or otherwise) log instance. Each log instance
may contain multiple log sinks (appenders in log4j language). The following jetty.xml configures the
default log instance by reseting it's default sinks (stderr) and adding a roll over file LogSink:<pre>
<Call class="org.mortbay.log.LogFactory" name="getFactory">
<Call name="getInstance">
<Arg/>
<Call name="reset"/>
<Call name="add">
<Arg>
<New class="org.mortbay.log.OutputStreamLogSink">
<Set name="filename"><SystemProperty name="jetty.home" default="."/>/logs/yyyy_mm_dd.jetty.log</Set>
<Set name="retainDays">90</Set>
<Set name="append">true</Set>
<Set name="logLabels">true</Set>
<Set name="logStackSize">true</Set>
<Set name="logStackTrace">false</Set>
<Set name="logOneLine">false</Set>
<Set name="suppressStack">false</Set>
<Set name="logTimeZone">GMT</Set>
</New>
</Arg>
</Call>
</Call>
</Call>
</pre>
</p>
<p>
To add a logImpl for a specific package name:<pre>
<Call class="org.mortbay.log.LogFactory" name="getFactory">
<Call name="setAttribute">
<Arg>org.mortbay.myapp.*</Arg>
<Arg>
<New class="org.mortbay.log.LogImpl">
<Call name="add">
<Arg>
<New class="org.mortbay.log.OutputStreamLogSink">
...
</New>
</Arg>
</Call>
</New>
</Arg>
</Call>
</Call>
</pre>
</p>
<p>
To alias another package (or other) name to an existing log impl:
<pre>
<Call class="org.mortbay.log.LogFactory" name="getFactory">
<Call name="setAttribute">
<Arg>org.mortbay.otherpackage</Arg>
<Arg>org.mortbay.mypackage.*</Arg>
</Call>
</Call>
</pre>
</p>
<p>
The log messages that are passed from a log to a LogSink are controlled by the LogImpl API or via
system properties:<PRE>
DEBUG - if set debugging is output is enabled.
DEBUG_PATTERNS - A list of substring patterns used to match against log information for
fine grained control of debug logging.
DEBUG_VERBOSE - If set to a positive integer, trace and info are enabled.
If set to zero, then info is enabled.
</pre>
For example:<pre>
java -DDEBUG -DDEBUG_PATTERNS=main,org.mortbay.http -DDEBUG_VERBOSE=1 -jar start.jar
</pre>
This turns on TRACE and DEBUG messages for the main thread and from classes in the org.mortbay.http package.
Typically running with just <code>-DDEBUG</code> gives a reasonable amount of additional information about what
Jetty is doing.
</p>
<p>
<i>Note, for JettyPlus the jetty log
is not configured by default because several components use log4j directly. Thus the commons logging
discovery mechanism finds the log4j.jar in extra/ext which is configured from extra/resources/log4j.properties.</i>
</p>
<h3>Alternate Log Implementations</h3>
<p>
To use an alternative log mechanism, the commons logging discovery mechanism needs to be used.
By default, this is turned off in Jetty with the org.mortbay.log.LogFactory.noDiscovery system property
that is set in start.config. For example,
to use log4j you need to put the log4j.jar on the classpath (place it in the ext directory) and to run jetty
with a command like:<pre>
java -Dorg.mortbay.log.LogFactory.noDiscovery=false -jar start.jar
</pre>
You need to consult the documentation for those specific log mechanism to learn their configuration. You will also need
to copy a commons-logging.jar into $JETTY_HOME/ext directory, as only the commons-loggin-api.jar is shipped with the
Jetty distro.
</p>
<br/>
<h2>Context Logs</h2>
The
<a href="http://localhost:8080/javadoc/javax/servlet/ServletContext.html">javax.servlet.ServletContext</a> API provides
several log methods that a web application can use to log information and exceptions. These methods are directed to a
commons log selected by "org.mortbay.jetty.context."+name. The context name is used, which is the either display name (if set in the web.xml) or
the [virtualhost:]contextPath. This name can be used to map to a specific logger, or using the jetty log factory
it can be mapped to an existing log impl as follows:
<pre>
<Call class="org.apache.commons.logging.LogFactory" name="getFactory">
<Call name="setAttribute">
<Arg>org.mortbay.jetty.context./mycontext</Arg>
<Arg>org.mortbay.mypackage.*</Arg>
</Call>
</Call>
</pre>
<br/>
<h2>Application Logs</h2>
<p>The applications deployed within Jetty will often include their own logging mechanism such as log4j or commons
logging. Frequently these log mechanism can be configured directly and will not interfer with Jetty.
However, as commons logging and log4j are both popular logging mechanism and both rely on class loading for
configuration then there can be problems with the log implementations with the WEB-INF/lib directory of a
webapplication clashing with the mechanisms used by Jetty. If your webapplication suffers such problems, then it
is probably best to harmonize the logging used by jetty and the webapplication. For example if the webapplication
uses log4j, then configure Jetty (commons logging) to use log4j and then remove the log4j.jar from the webapplication.
</p>
