Logging and Debugging
Introduction
Jetty can be configured to log requests and/or debugging information.
An implementation of a logging facility is provided with the release that
can send logged data to System.err, System.out, a named file or a specified
OutputStream. If output is directed to a file, then log aging and
rollover is supported and configurable.
Jetty logging is designed to be flexible and thus it is possible to
write a custom logger and use it in place of the supplied logger. For
example, if Jetty is embedded in an application, then a custom logger
can be written to feed log events to application's native log mechanism.
All loggers are implementations of the
org.mortbay.util.LogSink interface. The supplied logger is
org.mortbay.util.OutputStreamLogSink.
Logging can be configured in four ways:
- via the Jetty API
- via XML configuration files
- a Debug servlet supplied with the release
- JMX MBeans
The first two of these methods are covered in the sections below on
Logging Requests and Debugging
.
The Debug servlet distributed
with the Jetty demonstration servlets
can change the logging and debugging settings of a running server. It is
configured by the $JETTY_HOME/etc/admin.xml file. As shipped,
it will start on port 8081. To login to it, use username admin
password admin.
Finally, the JMX MBeans provided by the
Jetty3Extra
package provides a mechanism to configure debugging and logging
at runtime. It also provides statistics reporting. A description of this
facility is, at the moment, beyond the scope of this tutorial.
Logging Requests
See RequestLog and
NCSARequestLog.
Requests can be logged at the server or context level by adding a
implementation of RequestLog to the server and/or context. NCSARequestLog is
an implementation of the defacto standard request log format in normal and
extended modes.
Debugging
Debugging information is logged via the collection of
org.mortbay.util.LogSink instances configured into the static
instance of org.mortbay.util.Log
. The static instance can be configured via the API, XML or java system
properties.
For example, to configure a debug log file that will be rolled over
(as indicated by the yyyy_mm_dd suffix indicates this):
java -DDEBUG -DLOG_FILE=./logs/debug_yyyy_mm_dd.log org.mortbay.jetty.Server
Example: Setting the debug log file
|
Jetty is instrumented with debugging statments provided by the
org.mortbay.util.Code class. Debugging directives control not
only the output file names, but also the verbosity of debug messages, and
even which classes may generate debug output.
Debug information is categorized as one of the following types:
ASSERT |
reports the outcome of a programmatic assertion |
WARN |
a programmer initiated warning, intended to be viewed
by technical staff |
FAIL |
a programmer initiated fatal error |
DEBUG |
general debug message |
The Java System properties that control debugging are as follows:
DEBUG |
Only if this property is set will any debug output
be produced
|
DEBUG_PATTERNS |
Can be set to a comma separated list of strings.
In this case, debug output is only produced from those classes whose
fully qualified class name contains one of the strings as a substring.
Eg.
- "MyClass" matches "org.mortbay.util.MyClass"
, "com.firm.stuff.MyClass"
- "com.firm" matches all classes in that package and
subpackages
- "com.firm, org.mortbay.util.Threadpool" matches
all com.firm classes the Threadpool class only
|
DEBUG_OPTIONS |
String of one letter options:
- 'W' suppresses warnings unless DEBUG
is on
- 'S' suppress stack frame dumps
|
DEBUG_VERBOSE |
An integer value available to the programmer for
deciding level of output verbosity. The Jetty code uses the following verbosity
settings:
|
For example, to enable debugging from the classes "SocketListener" and
"ThreadedServer" at a high level of verbosity :
java -DDEBUG \
-DLOG_FILE=./logs/debug_yyyy_mm_dd.log \
-DDEBUG_VERBOSE=99
-DDEBUG_PATTERNS="SocketListener,ThreadedServer"\
org.mortbay.jetty.Server
Example: Debug system properties
|
Debugging can also be configured using the Jetty XML mechanism. The
same example above can be presented as:
<Set name="Debug" class="org.mortbay.util.Code"
type="boolean">true</Set>
<Set name="Verbose" class="org.mortbay.util.Code"
type="int">99</Set>
<Set name="DebugPatterns" class="org.mortbay.util.Code"
type="String">"SocketListener,ThreadedServer"</Set>
<Call name="instance" class="org.mortbay.util.Log">
<Call name="disableLog"/>
<Call name="add">
<Arg>
<New class="org.mortbay.util.WriterLogSink">
<Arg><SystemProperty name="jetty.home"
default="."/>/logs/debug_yyyy_mm_dd.log</Arg>
<Set name="RetainDays">90</Set>
<Set name="Append">true</Set>
<Call name="start"/>
</New>
</Arg>
</Call>
</Call>
|
XML Example: Debug set up
|