<body>
- <section name="Important note">
- <p>
- 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 <a href="extras.html">extras components</a> documentation), which includes
- a full commons-logging implementation.
- </p>
- </section>
-
<section name="Introduction">
- <p>
- Tomcat 7.0 uses
- <a href="http://commons.apache.org/logging">Commons Logging</a>
- throughout its internal code allowing the
- developer to choose a logging configuration that suits their needs, e.g
- java.util.logging or
- <a href="http://logging.apache.org/log4j">Log4J</a>.
- Commons Logging provides Tomcat the ability to log
- hierarchically across various log levels without needing to rely on a particular
- logging implementation.
- </p>
- <p>
- An important consequence for Tomcat 7.0 is that the <Logger> element found in
- previous versions to create a <code>localhost_log</code> 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.
- </p>
-
- </section>
-
- <section name="log4j">
- <p>
- Tomcat 7.0 has done away with <code>localhost_log</code> 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 <code>stdout</code> log.
- </p>
-
<p>
- 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 <code>stdout</code> as discussed above.
+ Tomcat 7.0 uses
+ <a href="http://commons.apache.org/logging">Commons Logging</a>
+ throughout its internal code allowing the
+ developer to choose a logging configuration that suits their needs, e.g
+ java.util.logging or
+ <a href="http://logging.apache.org/log4j">Log4J</a>.
+ Commons Logging provides Tomcat with the ability to log
+ hierarchically across various log levels without needing to rely on a
+ particular logging implementation.
</p>
<p>
- 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
+ <a href="extras.html">extras</a> 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.
</p>
<p>
- <ol>
- <li>Create a file called log4j.properties with the following content
- and save it into $CATALINA_HOME/lib.
- <source>
- log4j.rootLogger=debug, R <br />
- log4j.appender.R=org.apache.log4j.RollingFileAppender <br />
- log4j.appender.R.File=${catalina.home}/logs/tomcat.log <br />
- log4j.appender.R.MaxFileSize=10MB <br />
- log4j.appender.R.MaxBackupIndex=10 <br />
- log4j.appender.R.layout=org.apache.log4j.PatternLayout <br />
- log4j.appender.R.layout.ConversionPattern=%p %t %c - %m%n <br />
- log4j.logger.org.apache.catalina=DEBUG, R
- </source>
- </li>
-
- <li><a href="http://logging.apache.org/log4j">Download Log4J</a>
- (v1.2 or later) and place the log4j jar in $CATALINA_HOME/lib.</li>
-
- <li>Build or download the additional logging components. See the
- <a href="extras.html">extras components</a> documentation for details.</li>
-
- <li>Replace <code>$CATALINA_HOME/bin/tomcat-juli.jar</code> with
- <code>output/extras/tomcat-juli.jar</code>.</li>
-
- <li>Place <code>output/extras/tomcat-juli-adapters.jar</code> in
- $CATALINA_HOME/lib.</li>
-
- <li>Start Tomcat</li>
- </ol>
+ Tomcat no longer uses <code>localhost_log</code> 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 <code>stdout</code> log.
</p>
- <p>
- 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.
- </p>
-
- <p>
- 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.
-
- <ul>
- <li>log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost]=DEBUG, R</li>
- <li>log4j.logger.org.apache.catalina.core=DEBUG, R</li>
- <li>log4j.logger.org.apache.catalina.session=DEBUG, R</li>
- </ul>
-
- 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.
- </p>
-
- <p>
- Your web applications should certainly use their own log4j configuration.
- This is valid <i>with</i> 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
- <a href="http://logging.apache.org/log4j/docs/documentation.html">log4j documentation</a>
- for more options. This page is intended only as a bootstrapping guide.
- </p>
-
</section>
<section name="java.util.logging">
<p>
- 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.
</p>
<p>
- 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:
<ul>
- <li>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
+ <li>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
<code>$JAVA_HOME/jre/lib</code>.
- Alternately, it can also use a global configuration file located elsewhere by using the
- system property <code>java.util.logging.config.file</code>, or programmatic configuration using
+ Alternately, it can also use a global configuration file located elsewhere
+ by using the system property <code>java.util.logging.config.file</code>,
+ or programmatic configuration using
<code>java.util.logging.config.class</code>.</li>
- <li>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.</li>
+ <li>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.</li>
</ul>
</p>
<p>
- 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.
</p>
<p>
<source>org.apache.catalina.level=FINEST</source>
</p>
<p>
- 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:
<ul>
- <li>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,
- <code>22foobar.</code> is a valid prefix.</li>
- <li>As in Java 6.0, loggers can define a list of handlers using the <code>loggerName.handlers</code>
- property.</li>
- <li>By default, loggers will not delegate to their parent if they have associated handlers. This
- may be changed per logger using the <code>loggerName.useParentHandlers</code> property, which accepts
- a boolean value.</li>
- <li>The root logger can define its set of handlers using a <code>.handlers</code> property.</li>
- <li>System property replacement for property values which start with ${systemPropertyName}.</li>
+ <li>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, <code>22foobar.</code> is a valid
+ prefix.</li>
+ <li>As in Java 6.0, loggers can define a list of handlers using the
+ <code>loggerName.handlers</code> property.</li>
+ <li>By default, loggers will not delegate to their parent if they have
+ associated handlers. This may be changed per logger using the
+ <code>loggerName.useParentHandlers</code> property, which accepts a
+ boolean value.</li>
+ <li>The root logger can define its set of handlers using a
+ <code>.handlers</code> property.</li>
+ <li>System property replacement for property values which start with
+ ${systemPropertyName}.</li>
</ul>
</p>
<p>
</p>
<p>
- 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:
<source>
handlers = org.apache.juli.FileHandler, java.util.logging.ConsoleHandler
</section>
+ <section name="log4j">
+ <p>
+ 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.
+ </p>
+
+ <p>
+ <ol>
+ <li>Create a file called log4j.properties with the following content
+ and save it into $CATALINA_HOME/lib.
+ <source>
+ log4j.rootLogger=INFO, R <br />
+ log4j.appender.R=org.apache.log4j.RollingFileAppender <br />
+ log4j.appender.R.File=${catalina.home}/logs/tomcat.log <br />
+ log4j.appender.R.MaxFileSize=10MB <br />
+ log4j.appender.R.MaxBackupIndex=10 <br />
+ log4j.appender.R.layout=org.apache.log4j.PatternLayout <br />
+ log4j.appender.R.layout.ConversionPattern=%p %t %c - %m%n
+ </source>
+ </li>
+
+ <li><a href="http://logging.apache.org/log4j">Download Log4J</a>
+ (v1.2 or later) and place the log4j jar in $CATALINA_HOME/lib.</li>
+
+ <li>Build or download the additional logging components. See the
+ <a href="extras.html">extras components</a> documentation for
+ details.</li>
+
+ <li>Replace <code>$CATALINA_HOME/bin/tomcat-juli.jar</code> with
+ <code>output/extras/tomcat-juli.jar</code>.</li>
+
+ <li>Place <code>output/extras/tomcat-juli-adapters.jar</code> in
+ $CATALINA_HOME/lib.</li>
+
+ <li>Start Tomcat</li>
+ </ol>
+ </p>
+
+ <p>
+ 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.
+ </p>
+
+ <p>
+ 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.
+
+ <source>
+ log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost]=DEBUG<br />
+ log4j.logger.org.apache.catalina.core=DEBUG<br />
+ log4j.logger.org.apache.catalina.session=DEBUG<br />
+ </source>
+
+ 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.
+ </p>
+
+ <p>
+ Your web applications should certainly use their own log4j configuration.
+ This is valid <i>with</i> 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
+ <a href="http://logging.apache.org/log4j/docs/documentation.html">log4j
+ documentation</a> for more options. This page is intended only as a
+ bootstrapping guide.
+ </p>
+
+ </section>
+
</body>
</document>
projects / tomcat7.0 / commitdiff