Jump to: navigation, search

Difference between revisions of "Jetty/Feature/Jetty Logging"

< Jetty‎ | Feature
 
(5 intermediate revisions by 2 users not shown)
Line 2: Line 2:
 
| introduction =  
 
| introduction =  
  
Jetty provides it's own logging mechanism that can work one of 3 modes: 1) Logging to directly to StdErr using org.eclipse.jetty.util.log.StdErrLog ; 2) Logging via Slf4j to any configured Slf4j log;  3) Logging to a custom logger written against the jetty API.
+
{{Jetty Redirect|http://www.eclipse.org/jetty/documentation/current/configuring-logging.html}}
  
With any logging mode, all logged events have a name and a level. The name is a Fully Qualified Class Name (FQCN). The logging framework you choose determines the level. While the meaning of the levels is pretty much the same across logging frameworks, the descriptive identifiers for those levels are different.  
+
Jetty provides logging via its own <code>org.eclipse.jetty.util.log.Logger</code> layer, and does not natively use any existing Java logging framework.
 +
 
 +
All logging events, produced via the Jetty logging layer, will have a name, a level, and a message.
 +
 
 +
The name being a FQCN (fully qualified class name) similar to how all existing Java logging frameworks operate.
 +
 
 +
Jetty logging, however, has a slightly different set of levels that it uses internally.
 +
 
 +
* WARN - this is used for events considered serious enough to inform and log, but not fatal.
 +
* INFO - informational events
 +
* DEBUG - debugging events (very noisy)
 +
* IGNORE - exception events that can be safely ignored, but might prove useful for some people.  (Note: this level might be reported as level DEBUG under some Java logging frameworks configurations, but will retain the 'ignore' phrase somewhere in the logging )
 +
 
 +
Also note, there is no FATAL or SEVERE events produced by jetty logging.
  
 
| body =  
 
| body =  
Line 10: Line 23:
 
==Selecting the Log Framework==
 
==Selecting the Log Framework==
  
If Jetty does not discover an slf4j jar on the classpath, then it will use the internal org.eclipse.jetty.util.log.StdErrLog logger. If an slf4j jar is on the classpath, then slf4j configuration mechanisms are used to select the actual logger used (eg logback, java.util.logging, or log4j,can all be used via slf4j).
+
The Jetty logging layer is configured via the <code>org.eclipse.jetty.util.log.Log</code> class and follows [http://git.eclipse.org/c/jetty/org.eclipse.jetty.project.git/tree/jetty-util/src/main/java/org/eclipse/jetty/util/log/Log.java these rules].
  
The logger used may also be controlled by the system property <tt>org.eclipse.jetty.util.log.class</tt>, which can be set to the classname of an implementation of the jetty Logger API.  For an example of a custom Logger, see http://download.eclipse.org/jetty/stable-7/xref/org/eclipse/jetty/util/log/JavaUtilLog.html
+
# Load Properties
 +
## First from a Classpath Resource called <code>jetty-logging.properties</code> (if found)
 +
## Then from the <code>System.getProperties()</code>
 +
# Determine the Log implementation.
 +
## If property <code>org.eclipse.jetty.util.log.class</code> is defined, load the class it defines as the Logger implementation from the server classpath
 +
## If the class <code>org.slf4j.Logger</code> exists in server classpath, then the jetty implementation becomes <code>org.eclipse.jetty.util.log.Slf4jLog</code>
 +
## If no logger implementation specified, then default to <code>org.eclipse.jetty.util.log.StdErrLog</code>
 +
 
 +
Note: that you can create your own custom logging by providing an implementation of the [http://download.eclipse.org/jetty/stable-7/apidocs/org/eclipse/jetty/util/log/Logger.html Jetty Logger API].  For an example of a custom Logger, see http://git.eclipse.org/c/jetty/org.eclipse.jetty.project.git/tree/jetty-util/src/main/java/org/eclipse/jetty/util/log/JavaUtilLog.java
  
 
}}
 
}}
Line 22: Line 43:
 
{| class="jetty-table"
 
{| class="jetty-table"
 
|-
 
|-
! scope=col width="300" | System Property
+
! scope=col width="300" | Logging Property
! scope=col width="600" | Project
+
! scope=col width="600" | Description
 
|-
 
|-
| <tt>&lt;some.package&gt;.LEVEL=&lt;level&gt;</tt>
+
| <tt>&lt;name&gt;.LEVEL=&lt;level&gt;</tt>
| Sets the logging level for all loggers within the <tt>some.package</tt> java package to the level, which can be INFO, DEBUG, WARN or NONEFor example, -Dorg.eclipse.jetty.http.LEVEL=DEBUG  would turn all loggers in the jetty HTTP package to DEBUG level.   If a Logging level is specified by more than one system property, then the most specific one is used.
+
| Sets the logging level for all logger within the <tt>name</tt> specified to the level, which can be (in increasing order of restriction) ALL,DEBUG,INFO,WARN,OFFThe name (or hierarchy) can be a specific fully qualified class or a package namespace, for example, -Dorg.eclipse.jetty.http.LEVEL=DEBUG  would be a package namespace approach to turn all loggers in the jetty HTTP package to DEBUG level, and -Dorg.eclipse.jetty.io.ChanelEndPoint.LEVEL=ALL  would turn on all logging events for the specific class, including DEBUG, INFO, WARN (and even special internally ignored exception casses).  If a Logging level is specified by more than one system property, then the most specific one is used.
 +
|-
 +
| <tt>&lt;name&gt;.SOURCE=&lt;boolean&gt;</tt>
 +
| Logger specific, attempt to print the java source file name and line number where the logging event originated from. <br/>Name must be a fully qualified class name (package name hierarchy is not supported by this configurable)  <br/>Warning: this is a slow operation and will have an impact on performance! <br/>Default: false
 +
|-
 +
| <tt>&lt;name&gt;.STACKS=&lt;boolean&gt;</tt>
 +
| Logger specific, control the display of stacktraces.<br/>Name must be a fully qualified class name (package name hierarchy is not supported by this configurable)<br/> Default: true
 
|-
 
|-
 
| <tt>org.eclipse.jetty.util.log.IGNORED=&lt;boolean&gt;</tt>
 
| <tt>org.eclipse.jetty.util.log.IGNORED=&lt;boolean&gt;</tt>
Line 32: Line 59:
 
|-
 
|-
 
| <tt>org.eclipse.jetty.util.log.stderr.SOURCE=&lt;boolean&gt;</tt>  
 
| <tt>org.eclipse.jetty.util.log.stderr.SOURCE=&lt;boolean&gt;</tt>  
| If set to true, then the source filename and line number of the LOG API call are included in the StdErrLog output
+
| Special Global Configuration, attempt to print the java source file name and line number where the logging event originated from. <br/>Default: false
 
|-
 
|-
 
| <tt>org.eclipse.jetty.util.log.stderr.LONG=&lt;boolean&gt;</tt>  
 
| <tt>org.eclipse.jetty.util.log.stderr.LONG=&lt;boolean&gt;</tt>  
| If set to true, then the long form FQCN is used in the StdErrLog output (defaults to ''false''). Otherwise FQCN are abbreviated to the form oejh.SomeClass instead of org.eclipse.jetty.http.SomeClass.
+
| Special Global Configuration, when true, output logging events to STDERR using long form, fully qualified class names.  when false, use abbreviated package names <br/>Default: false
 
|-
 
|-
 
| <tt>org.eclipse.jetty.util.log.DEBUG</tt>,  <tt>org.eclipse.jetty.util.log.stderr.DEBUG</tt>, <tt>DEBUG</tt> (deprecated)  
 
| <tt>org.eclipse.jetty.util.log.DEBUG</tt>,  <tt>org.eclipse.jetty.util.log.stderr.DEBUG</tt>, <tt>DEBUG</tt> (deprecated)  
Line 42: Line 69:
 
|}
 
|}
  
 +
===Changing log level in <tt>resources/jetty-logging.properties</tt>===
 +
 +
<source lang="robots">
 +
# Setup logging implementation
 +
org.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.StdErrLog
 +
org.eclipse.jetty.LEVEL=INFO
 +
# Make websocket more verbose for testing
 +
org.eclipse.jetty.websocket.LEVEL=DEBUG
 +
</source>
  
 
===Changing log level in <tt>etc/jetty.xml</tt>===
 
===Changing log level in <tt>etc/jetty.xml</tt>===
  
 
<source lang="xml">
 
<source lang="xml">
<Get class="org.eclipse.jetty.util.log.Log" name="log">
+
<Call class="org.eclipse.jetty.util.log.Log" name="getRootLogger">
    <Call name="setDebugEnabled">
+
  <Call name="setDebugEnabled">
        <Arg type="boolean">true</Arg>
+
    <Arg type="boolean">true</Arg>
    </Call>
+
  </Call>
</Get>
+
</Call>
 
</source>
 
</source>
  
Line 66: Line 102:
  
 
To enable access logging with Jetty, include the <tt>etc/jetty-requestlog.xml</tt> on Jetty startup.
 
To enable access logging with Jetty, include the <tt>etc/jetty-requestlog.xml</tt> on Jetty startup.
 +
 +
See [[Jetty/Tutorial/RequestLog| Jetty Request Logs]] for more information.

Latest revision as of 14:56, 23 April 2013



Introduction


Jetty provides logging via its own org.eclipse.jetty.util.log.Logger layer, and does not natively use any existing Java logging framework.

All logging events, produced via the Jetty logging layer, will have a name, a level, and a message.

The name being a FQCN (fully qualified class name) similar to how all existing Java logging frameworks operate.

Jetty logging, however, has a slightly different set of levels that it uses internally.

  • WARN - this is used for events considered serious enough to inform and log, but not fatal.
  • INFO - informational events
  • DEBUG - debugging events (very noisy)
  • IGNORE - exception events that can be safely ignored, but might prove useful for some people. (Note: this level might be reported as level DEBUG under some Java logging frameworks configurations, but will retain the 'ignore' phrase somewhere in the logging )

Also note, there is no FATAL or SEVERE events produced by jetty logging.

Selecting the Log Framework

The Jetty logging layer is configured via the org.eclipse.jetty.util.log.Log class and follows these rules.

  1. Load Properties
    1. First from a Classpath Resource called jetty-logging.properties (if found)
    2. Then from the System.getProperties()
  2. Determine the Log implementation.
    1. If property org.eclipse.jetty.util.log.class is defined, load the class it defines as the Logger implementation from the server classpath
    2. If the class org.slf4j.Logger exists in server classpath, then the jetty implementation becomes org.eclipse.jetty.util.log.Slf4jLog
    3. If no logger implementation specified, then default to org.eclipse.jetty.util.log.StdErrLog

Note: that you can create your own custom logging by providing an implementation of the Jetty Logger API. For an example of a custom Logger, see http://git.eclipse.org/c/jetty/org.eclipse.jetty.project.git/tree/jetty-util/src/main/java/org/eclipse/jetty/util/log/JavaUtilLog.java

Configuring Jetty StdErrLog

If the default Jetty logger is selected, then further System properties may be used to control what event levels are logged and what is the format of those logs.

Logging Property Description
<name>.LEVEL=<level> Sets the logging level for all logger within the name specified to the level, which can be (in increasing order of restriction) ALL,DEBUG,INFO,WARN,OFF. The name (or hierarchy) can be a specific fully qualified class or a package namespace, for example, -Dorg.eclipse.jetty.http.LEVEL=DEBUG would be a package namespace approach to turn all loggers in the jetty HTTP package to DEBUG level, and -Dorg.eclipse.jetty.io.ChanelEndPoint.LEVEL=ALL would turn on all logging events for the specific class, including DEBUG, INFO, WARN (and even special internally ignored exception casses). If a Logging level is specified by more than one system property, then the most specific one is used.
<name>.SOURCE=<boolean> Logger specific, attempt to print the java source file name and line number where the logging event originated from.
Name must be a fully qualified class name (package name hierarchy is not supported by this configurable)
Warning: this is a slow operation and will have an impact on performance!
Default: false
<name>.STACKS=<boolean> Logger specific, control the display of stacktraces.
Name must be a fully qualified class name (package name hierarchy is not supported by this configurable)
Default: true
org.eclipse.jetty.util.log.IGNORED=<boolean> If set to true, then exceptions that have been recorded as ignored with the LOG.ignore(throwable) API will be logged with a full stack trace. Otherwise ignored exceptions are either not logged, or logged in summary if the level is debug.
org.eclipse.jetty.util.log.stderr.SOURCE=<boolean> Special Global Configuration, attempt to print the java source file name and line number where the logging event originated from.
Default: false
org.eclipse.jetty.util.log.stderr.LONG=<boolean> Special Global Configuration, when true, output logging events to STDERR using long form, fully qualified class names. when false, use abbreviated package names
Default: false
org.eclipse.jetty.util.log.DEBUG, org.eclipse.jetty.util.log.stderr.DEBUG, DEBUG (deprecated) These are deprecated properties that are ignored with a warning if used.

Changing log level in resources/jetty-logging.properties

# Setup logging implementation
org.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.StdErrLog
org.eclipse.jetty.LEVEL=INFO
# Make websocket more verbose for testing
org.eclipse.jetty.websocket.LEVEL=DEBUG

Changing log level in etc/jetty.xml

<Call class="org.eclipse.jetty.util.log.Log" name="getRootLogger">
  <Call name="setDebugEnabled">
    <Arg type="boolean">true</Arg>
  </Call>
</Call>

Using etc/jetty-logging.xml

You can use etc/jetty-logging.xml to take all System.out and System.err output (from any source) and route it to a rolling log file. To do so, include etc/jetty-logging.xml on Jetty startup.

java -jar start.jar etc/jetty-logging.xml

Request Logging

Request logging (AKA access logging), refers to the logging of each request handled by the server. This is a different logging mechanism and in jetty is provided with an implementation of the well-established NCSA log file format. This log file format is standardized so that other tooling can use the information for other reasons.

To enable access logging with Jetty, include the etc/jetty-requestlog.xml on Jetty startup.

See Jetty Request Logs for more information.