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:

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