BACK | INDEX | EXIT | NEXT

# 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:

- 0
- 1
- >1

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

BACK | INDEX | EXIT | NEXT