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

From Eclipsepedia

< Jetty‎ | Feature
Jump to: navigation, search
m
 
(16 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{Jetty Feature
+
{{Jetty Reference
| introduction = (required)
+
| introduction =  
  
You can use Jetty with external logging frameworks, or you can use default Jetty logging.
+
{{Jetty Redirect|http://www.eclipse.org/jetty/documentation/current/configuring-logging.html}}
  
With any logging framework, all 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.
| body = (required)
+
==Jetty Logging with External Frameworks==
+
  
You can use a logging framework other than the default Jetty Log. You use SLF4J as a façade for a logging framework such as logback, java.util.logging, or log4j, and all logging events stream to that framework. The way you configure the framework determines what you see.  If, for example, you want to ignore all events below WARN level, or turn on FINE/DEBUG level on org.eclipse.jetty.io.nio?, now you can.
+
All logging events, produced via the Jetty logging layer, will have a name, a level, and a message.
  
The jetty-util module now houses org.eclipse.jetty.util.log.LOG, which is a Log façade for a logging implementation. By default, Jetty first looks for org.slf4j.impl.StaticLoggerBinder in the server classpath to configure an external logging framework. If it is not present, Jetty uses the internal logging mechanism, org.eclipse.jetty.util.log.StdErrLog.
+
The name being a FQCN (fully qualified class name) similar to how all existing Java logging frameworks operate.
  
For more information, see http://wiki.eclipse.org/Jetty#Javadoc_and_Source. For an example of a custom Logger, see http://download.eclipse.org/jetty/stable-7/xref/org/eclipse/jetty/util/log/JavaUtilLog.html
+
Jetty logging, however, has a slightly different set of levels that it uses internally.
  
==Default Jetty Logging–<tt>org.eclipse.jetty.util.log.StdErrLog</tt>==
+
* 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 )
  
The default Jetty log has one name for all logs, using a system property that turns on DEBUG and reports on predefined events that write to STDERR. You configure logging at startup.
+
Also note, there is no FATAL or SEVERE events produced by jetty logging.
  
Jetty logging includes some system properties that you can use to control filtering.  For example,
+
| body =
<tt>org.eclipse.jetty.util.log.stderr.DEBUG</tt> sets the level filter to DEBUG and higher, with the possible levels being IGNORE, DEBUG, INFO, and WARN. By default, Jetty filters from INFO and above, showing only INFO and WARN logs.
+
  
* With StdErrLog you always see INFO and WARN logs. You can add DEBUG and/or IGNORE logs.
+
==Selecting the Log Framework==
* With the exception of <tt>org.eclipse.jetty.util.log.class</tt> these system properties take boolean values (''true'' or ''false'').
+
  
You set these system properties when you start Jetty.
+
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 following system properties define Jetty Logging:
+
# 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>
  
{| class="jetty-table"
+
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
  
 +
}}
 +
 +
==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.
 +
 +
{| 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>org.eclipse.jetty.util.log.class>/tt>
+
| <tt>&lt;name&gt;.LEVEL=&lt;level&gt;</tt>
| Sets the implementation class for Jetty Logging. Allows you to use an external logging framework with Jetty.
+
| 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,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.
 
|-
 
|-
| <tt>org.eclipse.jetty.util.log.IGNORED</tt>
+
| <tt>&lt;name&gt;.SOURCE=&lt;boolean&gt;</tt>
| Shows the IGNORED logging events (ones not deemed pertinent.
+
| 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>org.eclipse.jetty.util.log.DEBUG</tt> (deprecated)
+
| <tt>&lt;name&gt;.STACKS=&lt;boolean&gt;</tt>
| Shows DEBUG events and up.
+
| 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.stderr.DEBUG</tt>
+
| <tt>org.eclipse.jetty.util.log.IGNORED=&lt;boolean&gt;</tt>
| Shows DEBUG events and up (for StdErrLog)
+
| 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.
 
|-
 
|-
| <tt>org.eclipse.jetty.util.log.SOURCE</tt> (deprecated)
+
| <tt>org.eclipse.jetty.util.log.stderr.SOURCE=&lt;boolean&gt;</tt>  
| Shows the output of the log.  
+
| 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.SOURCE</tt>  
+
| <tt>org.eclipse.jetty.util.log.stderr.LONG=&lt;boolean&gt;</tt>  
| Includes the source filename and line number in the StdErrLog output
+
| 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.stderr.LONG</tt>  
+
| <tt>org.eclipse.jetty.util.log.DEBUG</tt>,  <tt>org.eclipse.jetty.util.log.stderr.DEBUG</tt>, <tt>DEBUG</tt> (deprecated)  
| Uses the long form FQCN in the StdErrLog output (defaults to ''false'').
+
| These are deprecated properties that are ignored with a warning if used.
 
|-
 
|-
 
|}
 
|}
 +
 +
===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>===
 +
 +
<source lang="xml">
 +
<Call class="org.eclipse.jetty.util.log.Log" name="getRootLogger">
 +
  <Call name="setDebugEnabled">
 +
    <Arg type="boolean">true</Arg>
 +
  </Call>
 +
</Call>
 +
</source>
  
 
===Using <tt>etc/jetty-logging.xml</tt>===
 
===Using <tt>etc/jetty-logging.xml</tt>===
Line 66: Line 97:
 
</source>
 
</source>
  
===Using Access Logging===
+
===Request Logging===
  
Access logging, also called request logging, refers to a well-established NCSA log file format for all requests that the server processes. This log file format is standardized so that other tooling can use the information for other reasons.  
+
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 <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 15:56, 23 April 2013



Contents

[edit] 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

[edit] 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.

[edit] 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

[edit] 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>

[edit] 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

[edit] 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.