BACK INDEX EXIT NEXT

Logging and Debugging 

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.

Request Logs

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 webalizer. A standard request log entry includes the client IP, date, method, URL, result, size, referrer and user agent. eg:

  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"
Jetty supports pluggable Request logs and any class that implements org.mortbay.http.RequestLog may be plugged into HttpServer or HttpContext. Jetty provides an implementation called NCSARequestLog which supports the NCSA format in files that can be rolled over on a daily basis.

To configure a request log for the whole server in jetty.xml:

    <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>
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.

A request log can be added to a single webapp or context as follows:

  <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>
A context request log can also be configured in a jetty-web.xml file in a similar way.

Implementation Log

The implementation log is a stream of TRACE, DEBUG, INFO, WARN and ERROR messages from the Jetty implementation. Jetty 5 uses Jakarta Commons Logging with a default logger based on the Jetty 4 log. In addition, commons logging allows for other log implementations to be plugged in, including Log4J, JDK 1.4, and its own SimpleLog.

Jetty Log Implementation

The Jetty log implementation 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:

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

To add a logImpl for a specific package name:

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

To alias another package (or other) name to an existing log impl:

  <Call class="org.mortbay.log.LogFactory" name="getFactory">
    <Call name="setAttribute">
      <Arg>org.mortbay.otherpackage</Arg>
      <Arg>org.mortbay.mypackage.*</Arg>
    </Call>
  </Call>  

The log messages that are passed from a log to a LogSink are controlled by the LogImpl API or via system properties:

   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.
For example:
  java -DDEBUG -DDEBUG_PATTERNS=main,org.mortbay.http -DDEBUG_VERBOSE=1 -jar start.jar
This turns on TRACE and DEBUG messages for the main thread and from classes in the org.mortbay.http package. Typically running with just -DDEBUG gives a reasonable amount of additional information about what Jetty is doing.

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.

Alternate Log Implementations

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:

  java -Dorg.mortbay.log.LogFactory.noDiscovery=false -jar start.jar
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.


Context Logs

The javax.servlet.ServletContext 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:
  <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>  

Application Logs

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.