Date: Thu, 3 Sep 2009 13:20:49 +0000 Subject: [PATCH] An attempt to improve the logging doc: - discuss java.util.logging first as it is the default - remove duplicate output from log4j config - stick to 80 char width where possible git-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@810930 13f79535-47bb-0310-9956-ffa450edef68 --- webapps/docs/logging.xml | 310 ++++++++++++++++++++++++----------------------- 1 file changed, 156 insertions(+), 154 deletions(-) diff --git a/webapps/docs/logging.xml b/webapps/docs/logging.xml index 95c1bbcd5..0cbfd99b1 100644 --- a/webapps/docs/logging.xml +++ b/webapps/docs/logging.xml @@ -30,187 +30,107 @@ -

- By default, only java.util.logging is available for the core Tomcat, as Tomcat uses - a package renamed logging implementation which is hardcoded for that logger. Usage of - alternate loggers is available after building or downloading the extra components - (see the extras components documentation), which includes - a full commons-logging implementation. -

- Tomcat 7.0 uses - Commons Logging - throughout its internal code allowing the - developer to choose a logging configuration that suits their needs, e.g - java.util.logging or - Log4J. - Commons Logging provides Tomcat the ability to log - hierarchically across various log levels without needing to rely on a particular - logging implementation. -

- An important consequence for Tomcat 7.0 is that the <Logger> element found in - previous versions to create a localhost_log is no longer a valid nested element - of <Context>. Instead, the default Tomcat configuration will use java.util.logging. - If the developer wishes to collect detailed internal Tomcat logging (i.e what is happening - within the Tomcat engine), then they should configure a logging system such as java.util.logging - or log4j as detailed next. -

- -

- Tomcat 7.0 has done away with localhost_log which you may be familiar with - as the runtime exception/stack trace log. These types of error are usually thrown - by uncaught exceptions, but are still valuable to the developer. They can now be - found in the stdout log. -

- If you need to setup cross-context detailed logging from within Tomcat's code, - then you can use a simple log4j configuration. Note that this logging can be very - verbose depending on the log level you chose to use. Note also that a log4j logging - configuration is not going to produce stack trace type logging: those stack traces - are output to stdout as discussed above. + Tomcat 7.0 uses + Commons Logging + throughout its internal code allowing the + developer to choose a logging configuration that suits their needs, e.g + java.util.logging or + Log4J. + Commons Logging provides Tomcat with the ability to log + hierarchically across various log levels without needing to rely on a + particular logging implementation.

- Follow the following steps to setup a file named tomcat.log that has internal - Tomcat logging output to it: + By default, only java.util.logging is available for the logs generated by + the Tomcat internal loggers, as Tomcat uses a package renamed commons + logging implementation which is hardcoded to use java.util.logging. Use of + alternative logging frameworks requires building or downloading the + extras components which include a full + commons-logging implementation. Instructions for configuring the extras + components to enable log4j to be used for Tomcat's internal logging may be + found below.

Create a file called log4j.properties with the following content - and save it into $CATALINA_HOME/lib. - - log4j.rootLogger=debug, R
- log4j.appender.R=org.apache.log4j.RollingFileAppender
- log4j.appender.R.File=${catalina.home}/logs/tomcat.log
- log4j.appender.R.MaxFileSize=10MB
- log4j.appender.R.MaxBackupIndex=10
- log4j.appender.R.layout=org.apache.log4j.PatternLayout
- log4j.appender.R.layout.ConversionPattern=%p %t %c - %m%n
- log4j.logger.org.apache.catalina=DEBUG, R - -
Download Log4J - (v1.2 or later) and place the log4j jar in $CATALINA_HOME/lib.
Build or download the additional logging components. See the - extras components documentation for details.
Replace $CATALINA_HOME/bin/tomcat-juli.jar with - output/extras/tomcat-juli.jar.
Place output/extras/tomcat-juli-adapters.jar in - $CATALINA_HOME/lib.
Start Tomcat

+ Tomcat no longer uses localhost_log as the runtime + exception/stack trace log. These types of error are usually thrown by + uncaught exceptions, but are still valuable to the developer. They can now + be found in the stdout log.

- This log4j configuration sets up a file called tomcat.log in your - Tomcat logs folder with a maximum file size of 10MB and - up to 10 backups. DEBUG level is specified which will result in the - most verbose output from Tomcat. -

- -

- You can (and should) be more picky about which packages to include - in the logging. Tomcat 6 defines loggers by Engine and Host names. - For example, for a default Catalina localhost log, add this to the - end of the log4j.properties above. Note that there are known issues with - using this naming convention (with square brackets) in log4j XML based - configuration files, so we recommend you use a properties file as described - until a future version of log4j allows this convention. - -

log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost]=DEBUG, R
log4j.logger.org.apache.catalina.core=DEBUG, R
log4j.logger.org.apache.catalina.session=DEBUG, R

- - Be warned a level of DEBUG will produce megabytes of logging and slow startup - of Tomcat. This level should be used sparingly when debugging of internal Tomcat - operations is required. -

- -

- Your web applications should certainly use their own log4j configuration. - This is valid with the above configuration. You would place a similar log4j.properties - file in your web application's WEB-INF/classes folder, and log4j1.2.8.jar into - WEB-INF/lib. Then specify your package level logging. This is a basic setup of log4j - which does *not* require Commons-Logging, - and you should consult the - log4j documentation - for more options. This page is intended only as a bootstrapping guide. -

- The default implementation of java.util.logging provided in the JDK is too limited to be - useful. A limitation of JDK Logging appears to be the inability to have per-web application logging, - as the configuration is per-VM. As a result, Tomcat will, in the default configuration, - replace the default LogManager implementation with a container friendly implementation - called JULI, which addresses these shortcomings. It supports the same configuration mechanisms - as the standard JDK java.util.logging, using either a programmatic approach, or properties - files. The main difference is that per-classloader properties files can be set (which enables easy - redeployment friendly webapp configuration), and the properties files support slightly extended - constructs which allows more freedom for defining handlers and assigning them to loggers. + The default implementation of java.util.logging provided in the JDK is too + limited to be useful. A limitation of JDK Logging appears to be the + inability to have per-web application logging, as the configuration is + per-VM. As a result, Tomcat will, in the default configuration, replace the + default LogManager implementation with a container friendly implementation + called JULI, which addresses these shortcomings. It supports the same + configuration mechanisms as the standard JDK java.util.logging, using either + a programmatic approach, or properties files. The main difference is that + per-classloader properties files can be set (which enables easy redeployment + friendly webapp configuration), and the properties files support slightly + extended constructs which allows more freedom for defining handlers and + assigning them to loggers.

- JULI is enabled by default in Tomcat 7.0, and supports per classloader configuration, in addition to - the regular global java.util.logging configuration. This means that logging can be configured at - the following layers: + JULI is enabled by default in Tomcat 7.0, and supports per classloader + configuration, in addition to the regular global java.util.logging + configuration. This means that logging can be configured at the following + layers:

In the JDK's logging.properties file. Check - your JAVA_HOME environment setting to see which JDK Tomcat is using. The file will be in +
In the JDK's logging.properties file. Check your JAVA_HOME environment + setting to see which JDK Tomcat is using. The file will be in $JAVA_HOME/jre/lib. - Alternately, it can also use a global configuration file located elsewhere by using the - system property java.util.logging.config.file, or programmatic configuration using + Alternately, it can also use a global configuration file located elsewhere + by using the system property java.util.logging.config.file, + or programmatic configuration using java.util.logging.config.class.
In each classloader using a logging.properties file. This means that it is possible to have a - configuration for the Tomcat core, as well as separate configurations for each webapps which will - have the same lifecycle as the webapps.
In each classloader using a logging.properties file. This means that + it is possible to have a configuration for the Tomcat core, as well as + separate configurations for each webapps which will have the same + lifecycle as the webapps.

- The default logging.properties specifies a ConsoleHandler for routing logging to stdout and - also a FileHandler. A handler's log level threshold can be set using SEVERE, WARNING, INFO, - CONFIG, FINE, FINER, FINEST or ALL. The logging.properties shipped with JDK is set to INFO. You - can also target specific packages to collect logging from and specify a level. Here is how - you would set debugging from Tomcat. You would need to ensure the ConsoleHandler's level is also - set to collect this threshold, so FINEST or ALL should be set. Please refer to Sun's java.util.logging - documentation for the complete details. + The default logging.properties specifies a ConsoleHandler for routing + logging to stdout and also a FileHandler. A handler's log level threshold + can be set using SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST or ALL. + The logging.properties shipped with JDK is set to INFO. You can also target + specific packages to collect logging from and specify a level. Here is how + you would set debugging from Tomcat. You would need to ensure the + ConsoleHandler's level is also set to collect this threshold, so FINEST or + ALL should be set. Please refer to Sun's java.util.logging documentation for + the complete details.

org.apache.catalina.level=FINEST

- The configuration used by JULI is extremely similar, but uses a few extensions to allow better - flexibility in assigning loggers. The main differences are: + The configuration used by JULI is extremely similar, but uses a few + extensions to allow better flexibility in assigning loggers. The main + differences are:

A prefix may be added to handler names, so that multiple handlers of a single class may be - instantiated. A prefix is a String which starts with a digit, and ends with '.'. For example, - 22foobar. is a valid prefix.
As in Java 6.0, loggers can define a list of handlers using the loggerName.handlers - property.
By default, loggers will not delegate to their parent if they have associated handlers. This - may be changed per logger using the loggerName.useParentHandlers property, which accepts - a boolean value.
The root logger can define its set of handlers using a .handlers property.
System property replacement for property values which start with ${systemPropertyName}.
A prefix may be added to handler names, so that multiple handlers of a + single class may be instantiated. A prefix is a String which starts with a + digit, and ends with '.'. For example, 22foobar. is a valid + prefix.
As in Java 6.0, loggers can define a list of handlers using the + loggerName.handlers property.
By default, loggers will not delegate to their parent if they have + associated handlers. This may be changed per logger using the + loggerName.useParentHandlers property, which accepts a + boolean value.
The root logger can define its set of handlers using a + .handlers property.
System property replacement for property values which start with + ${systemPropertyName}.

@@ -273,8 +193,8 @@ org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/admin].handlers

- Example logging.properties for the servlet-examples web application to be placed - in WEB-INF/classes inside the web application: + Example logging.properties for the servlet-examples web application to be + placed in WEB-INF/classes inside the web application: handlers = org.apache.juli.FileHandler, java.util.logging.ConsoleHandler @@ -294,5 +214,87 @@ java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

+ This section explains how to configure Tomcat to use log4j rather than + java.util.logging for all Tomcat's internal logging. The following steps + describe configuring log4j to output Tomcat's internal logging to a file + named tomcat.log. +

+ +

Create a file called log4j.properties with the following content + and save it into $CATALINA_HOME/lib. + + log4j.rootLogger=INFO, R
+ log4j.appender.R=org.apache.log4j.RollingFileAppender
+ log4j.appender.R.File=${catalina.home}/logs/tomcat.log
+ log4j.appender.R.MaxFileSize=10MB
+ log4j.appender.R.MaxBackupIndex=10
+ log4j.appender.R.layout=org.apache.log4j.PatternLayout
+ log4j.appender.R.layout.ConversionPattern=%p %t %c - %m%n + +
Download Log4J + (v1.2 or later) and place the log4j jar in $CATALINA_HOME/lib.
Build or download the additional logging components. See the + extras components documentation for + details.
Replace $CATALINA_HOME/bin/tomcat-juli.jar with + output/extras/tomcat-juli.jar.
Place output/extras/tomcat-juli-adapters.jar in + $CATALINA_HOME/lib.
Start Tomcat

+ +

+ This log4j configuration sets up a file called tomcat.log in your + Tomcat logs folder with a maximum file size of 10MB and + up to 10 backups. INFO level is specified which will result in a similar + level of detail to the standard java.util.logging confgiuration. Use DEBUG + level logging for the most verbose output from Tomcat. +

+ +

+ You can (and should) be more picky about which packages to include + in the logging. Tomcat 7 defines loggers by Engine and Host names. + For example, for a more detailed Catalina localhost log, add this to the + end of the log4j.properties above. Note that there are known issues with + using this naming convention (with square brackets) in log4j XML based + configuration files, so we recommend you use a properties file as + described until a future version of log4j allows this convention. + + + log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost]=DEBUG
+ log4j.logger.org.apache.catalina.core=DEBUG
+ log4j.logger.org.apache.catalina.session=DEBUG
+ + + Be warned a level of DEBUG will produce megabytes of logging and slow + startup of Tomcat. This level should be used sparingly when debugging of + internal Tomcat operations is required. +

+ +

+ Your web applications should certainly use their own log4j configuration. + This is valid with the above configuration. You would place a + similar log4j.properties file in your web application's WEB-INF/classes + directory, and log4jx.y.z.jar into WEB-INF/lib. Then specify your package + level logging. This is a basic setup of log4j which does *not* require + Commons-Logging, and you should consult the + log4j + documentation for more options. This page is intended only as a + bootstrapping guide. +

+ +

+ -- 2.11.0