Author: kkolinko
Date: Sat Apr 2 00:38:14 2011
New Revision: 1087942
URL: http://svn.apache.org/viewvc?rev=1087942&view=rev
Log:
Improve the logging documentation
Updated the comment in conf/logging.properties as well.
CTR: docs
Modified:
tomcat/tc6.0.x/trunk/conf/logging.properties
tomcat/tc6.0.x/trunk/webapps/docs/changelog.xml
tomcat/tc6.0.x/trunk/webapps/docs/logging.xml
Modified: tomcat/tc6.0.x/trunk/conf/logging.properties
URL:
http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/conf/logging.properties?rev=1087942&r1=1087941&r2=1087942&view=diff
==============================================================================
--- tomcat/tc6.0.x/trunk/conf/logging.properties (original)
+++ tomcat/tc6.0.x/trunk/conf/logging.properties Sat Apr 2 00:38:14 2011
@@ -56,9 +56,9 @@ org.apache.catalina.core.ContainerBase.[
org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/host-manager].level
= INFO
org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/host-manager].handlers
= 4host-manager.org.apache.juli.FileHandler
-# For example, set the com.xyz.foo logger to only log SEVERE
-# messages:
+# For example, to log debug messages in ContextConfig and HostConfig
+# classes and to log only warnings and errors in other
+# org.apache.catalina.** classes, uncomment these lines:
#org.apache.catalina.startup.ContextConfig.level = FINE
#org.apache.catalina.startup.HostConfig.level = FINE
-#org.apache.catalina.session.ManagerBase.level = FINE
-#org.apache.catalina.core.AprLifecycleListener.level=FINE
+#org.apache.catalina.level = WARNING
Modified: tomcat/tc6.0.x/trunk/webapps/docs/changelog.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/changelog.xml?rev=1087942&r1=1087941&r2=1087942&view=diff
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/changelog.xml (original)
+++ tomcat/tc6.0.x/trunk/webapps/docs/changelog.xml Sat Apr 2 00:38:14 2011
@@ -92,6 +92,9 @@
<bug>50804</bug>: Update links for Servlet 2.5 and JSP 2.1 Javadoc.
(markt)
</fix>
+ <update>
+ Improve Tomcat Logging documentation. (kkolinko)
+ </update>
</changelog>
</subsection>
</section>
Modified: tomcat/tc6.0.x/trunk/webapps/docs/logging.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/logging.xml?rev=1087942&r1=1087941&r2=1087942&view=diff
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/logging.xml (original)
+++ tomcat/tc6.0.x/trunk/webapps/docs/logging.xml Sat Apr 2 00:38:14 2011
@@ -65,11 +65,11 @@
</p>
<ul>
<li>
- Use logging API provided by the Java Servlets specification,
- <code>javax.servlet.ServletContext.log(...)</code>
+ Use system logging API, <code>java.util.logging</code>.
</li>
<li>
- Use system logging API, <code>java.util.logging</code>.
+ Use logging API provided by the Java Servlets specification,
+ <code>javax.servlet.ServletContext.log(...)</code>
</li>
<li>
Use any logging framework of its choice.
@@ -85,6 +85,8 @@
by the system and is shared across web applications.
</p>
+ <subsection name="java.util.logging">
+
<p>
Apache Tomcat has its own implementation of several key elements of
<code>java.util.logging</code> API. This implementation is called "JULI".
@@ -94,14 +96,30 @@
logging configurations. It is also notified by Tomcat when a web
application
is unloaded from memory, so that the references to its classes can be
cleared, preventing memory leaks.
+ </p>
+
+ <p>
This <code>java.util.logging</code> implementation is enabled by
providing
certain system properties when starting Java. The Apache Tomcat startup
scripts do this for you, but if you are using different tools to run
Tomcat (such as jsvc, or running Tomcat from within an IDE), you should
take care of them by yourself.
+ </p>
+
+ <p>
+ More details about java.util.logging may be found in the documentation
+ for your JDK and on its Javadoc pages for the
<code>java.util.logging</code>
+ package.
+ </p>
+
+ <p>
More details about Tomcat JULI may be found below.
</p>
+ </subsection>
+
+ <subsection name="Servlets logging API">
+
<p>
The calls to <code>javax.servlet.ServletContext.log(...)</code> to write
log messages are handled by internal Tomcat logging. Such messages are
@@ -114,34 +132,31 @@
</p>
<p>
- Old applications that still use <code>System.out</code> or
<code>System.err</code>
- can be tricked, by setting <code>swallowOutput</code> attribute on a
- <a href="config/context.html">Context</a>. If the attribute is set to
- <code>true</code>, calls to <code>System.out/err</code> during request
- processing will be intercepted, and their output will be fed to the
- logging subsystem using the
- <code>javax.servlet.ServletContext.log(...)</code> calls.<br />
- <strong>Note</strong>, that this feature is actually a trick,
- and works only with direct calls to <code>System.out/err</code>,
- and only during request processing cycle. It cannot be used to intercept
- logging frameworks that themselves write to the system streams,
- as those start early and may obtain a direct reference to the streams.
+ The Servlets logging API predates the <code>java.util.logging</code> API
+ that is now provided by Java. As such, it does not offer you much
options.
+ E.g., you cannot control the log levels. It can be noted, though, that
+ in Apache Tomcat implementation the calls to
<code>ServletContext.log(String)</code>
+ or <code>GenericServlet.log(String)</code> are logged at the INFO level.
+ The calls to <code>ServletContext.log(String, Throwable)</code> or
+ <code>GenericServlet.log(String, Throwable)</code>
+ are logged at the ERROR level.
</p>
+ </subsection>
+
+ <subsection name="Console">
+
<p>
- The default logging configuration in Apache Tomcat writes the same
- messages to the console and to a log file. This is great when using
- Tomcat for development, but usually is not needed in production.
When running Tomcat on unixes, the console output is usually redirected
- to a file named <code>catalina.out</code>. The name is configurable
+ to the file named <code>catalina.out</code>. The name is configurable
using an environment variable. (See the startup scripts).
- Whatever is written to <code>System.err/out</code> will be logged in
+ Whatever is written to <code>System.err/out</code> will be caught into
that file. That may include:
</p>
<ul>
- <li>Thread dumps, if you requested them via a system signal</li>
<li>Uncaught exceptions printed by
<code>java.lang.ThreadGroup.uncaughtException(..)</code></li>
+ <li>Thread dumps, if you requested them via a system signal</li>
</ul>
<p>
@@ -150,11 +165,41 @@
</p>
<p>
+ The default logging configuration in Apache Tomcat writes the same
+ messages to the console and to a log file. This is great when using
+ Tomcat for development, but usually is not needed in production.
+ </p>
+
+ <p>
+ Old applications that still use <code>System.out</code> or
<code>System.err</code>
+ can be tricked by setting <code>swallowOutput</code> attribute on a
+ <a href="config/context.html">Context</a>. If the attribute is set to
+ <code>true</code>, the calls to <code>System.out/err</code> during
request
+ processing will be intercepted, and their output will be fed to the
+ logging subsystem using the
+ <code>javax.servlet.ServletContext.log(...)</code> calls.<br />
+ <strong>Note</strong>, that the <code>swallowOutput</code> feature is
+ actually a trick, and it has its limitations.
+ It works only with direct calls to <code>System.out/err</code>,
+ and only during request processing cycle. It may not work in other
+ threads that might be created by the application. It cannot be used to
+ intercept logging frameworks that themselves write to the system streams,
+ as those start early and may obtain a direct reference to the streams
+ before the redirection takes place.
+ </p>
+
+ </subsection>
+
+ <subsection name="Access logging">
+
+ <p>
A related, but different feature is access logging. It can be configured
as a valve at the Context, or Host, or Engine. See <a
href="config/valve.html">Valves</a>
documentation for more details.
</p>
+ </subsection>
+
</section>
<section name="Using java.util.logging (default)">
@@ -178,60 +223,75 @@
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
- <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
- <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>Globally. That is usually done in the
+ <code>${catalina.base}/conf/logging.properties</code> file.
+ The file is specified by the <code>java.util.logging.config.file</code>
+ System property which is set by the startup scripts.
+ If it is not readable or is not configured, the default is to use the
+ <code>${java.home}/lib/logging.properties</code> file in the JRE.
+ </li>
+ <li>In the web application. The file will be
+ <code>WEB-INF/classes/logging.properties</code>
+ </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 <code>logging.properties</code> in the JRE specifies a
+ <code>ConsoleHandler</code> that routes logging to System.err.
+ The default <code>conf/logging.properties</code> in Apache Tomcat also
+ adds several <code>FileHandler</code>s that write to files.
+ </p>
+ <p>
+ A handler's log level threshold is INFO by default and can be set using
+ SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST or ALL.
+ You can also target specific packages to collect logging from and specify
+ a level.
+ </p>
+ <p>
+ Here is how you would set debugging from Tomcat. You would need to ensure
the
+ ConsoleHandler's (or FileHandler's') level is also set to collect this
threshold,
+ so FINEST or ALL should be set. Please refer to
<code>java.util.logging</code>
+ documentation in the JDK 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
+ The configuration used by JULI is extremely similar to the one supported by
+ plain <code>java.util.logging</code>, but uses a few
extensions to allow better flexibility in assigning loggers. The main
differences are:
- <ul>
+ </p>
+ <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>System property replacement is performed for property values which
+ contain ${systemPropertyName}.</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
+ <li>The root logger can define its set of handlers using the
<code>.handlers</code> property.</li>
- <li>Logging is not buffered by default. To configure buffering, use the
+ </ul>
+ <p>
+ There are several additional implementation classes, that can be used
+ together with the ones provided by Java. The notable one is
+ <code>org.apache.juli.FileHandler</code>.
+ </p>
+ <p>
+ <code>org.apache.juli.FileHandler</code> supports buffering of the
+ logs. The buffering is not enabled by default. To configure it, use the
<code>bufferSize</code> property of a handler. A value of <code>0</code>
uses system default buffering (typically an 8K buffer will be used). A
value of <code><0</code> forces a writer flush upon each log write. A
value <code>>0</code> uses a BufferedOutputStream with the defined
value but note that the system default buffering will also be
- applied.</li>
- <li>System property replacement is performed for property values which
- contain ${systemPropertyName}.</li>
- </ul>
+ applied.
</p>
<p>
Example logging.properties file to be placed in $CATALINA_BASE/conf:
@@ -239,7 +299,6 @@
handlers = 1catalina.org.apache.juli.FileHandler, \
2localhost.org.apache.juli.FileHandler, \
3manager.org.apache.juli.FileHandler, \
- 4admin.org.apache.juli.FileHandler, \
java.util.logging.ConsoleHandler
.handlers = 1catalina.org.apache.juli.FileHandler,
java.util.logging.ConsoleHandler
@@ -260,11 +319,7 @@ handlers = 1catalina.org.apache.juli.Fil
3manager.org.apache.juli.FileHandler.level = FINE
3manager.org.apache.juli.FileHandler.directory = ${catalina.base}/logs
3manager.org.apache.juli.FileHandler.prefix = manager.
-
-4admin.org.apache.juli.FileHandler.level = FINE
-4admin.org.apache.juli.FileHandler.directory = ${catalina.base}/logs
-4admin.org.apache.juli.FileHandler.prefix = admin.
-4admin.org.apache.juli.FileHandler.bufferSize = 16384
+3manager.org.apache.juli.FileHandler.bufferSize = 16384
java.util.logging.ConsoleHandler.level = FINE
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
@@ -283,14 +338,13 @@ org.apache.catalina.core.ContainerBase.[
org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/manager].handlers
= \
3manager.org.apache.juli.FileHandler
-org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/admin].level =
INFO
-org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/admin].handlers
= \
- 4admin.org.apache.juli.FileHandler
-
-# For example, set the org.apache.catalina.util.LifecycleBase logger to log
-# each component that extends LifecycleBase changing state:
-#org.apache.catalina.util.LifecycleBase.level = FINE
- </source>
+# For example, to log debug messages in ContextConfig and HostConfig
+# classes and to log only warnings and errors in other
+# org.apache.catalina.** classes, uncomment these lines:
+#org.apache.catalina.startup.ContextConfig.level = FINE
+#org.apache.catalina.startup.HostConfig.level = FINE
+#org.apache.catalina.level = WARNING
+</source>
</p>
<p>
@@ -310,17 +364,49 @@ org.apache.juli.FileHandler.prefix = ser
java.util.logging.ConsoleHandler.level = FINE
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
- </source>
+</source>
</p>
+ <subsection name="References">
+ <p>See the following resources for additional information:</p>
+ <ul>
+ <li>Tomcat Javadoc for the
+ <a
href="api/org/apache/juli/package-summary.html"><code>org.apache.juli</code></a>
+ package.
+ </li>
+ <li>Oracle Java 6 Javadoc for the
+ <a
href="http://download.oracle.com/javase/6/docs/api/java/util/logging/package-summary.html";><code>java.util.logging</code></a>
+ package.
+ </li>
+ </ul>
+ </subsection>
+
</section>
<section name="Using 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.
+ This section explains how to configure Tomcat to use
+ <a href="http://logging.apache.org/log4j/";>log4j</a> rather than
+ java.util.logging for all Tomcat's internal logging.
+ </p>
+ <p>Note, that</p>
+ <ul>
+ <li>This exposes log4j libraries to the web applications through the
+ Common classloader. See <a href="class-loader-howto.html">class
loading</a>
+ for details. The web applications using
+ <a href="http://commons.apache.org/logging";>Apache Commons Logging</a>
+ library are likely to automatically choose log4j as the underlying
+ logging implementation.</li>
+ <li>The <code>java.util.logging</code> API is still available, for
+ those who use it directly. Removal of the
+ <code>${catalina.base}/conf/logging.properties</code> file, mentioned
+ as one of the steps below, causes it to fallback to the default
+ configuration configured in JRE, which is to use a ConsoleHandler and
+ do not create any files.</li>
+ </ul>
+ <p>
+ The following steps describe configuring log4j to output Tomcat's
+ internal logging.
</p>
<ol>
@@ -383,7 +469,11 @@ log4j.logger.org.apache.catalina.core.Co
<code>output/extras/tomcat-juli.jar</code>.</li>
<li>Place <code>output/extras/tomcat-juli-adapters.jar</code> in
- $CATALINA_HOME/lib.</li>
+ $CATALINA_HOME/lib.<br />
+ Note, that <code>tomcat-juli.jar</code> and
+ <code>tomcat-juli-adapters.jar</code> go into different
+ directories. While the first one goes into <code>bin</code>, this
+ one goes into <code>lib</code>.</li>
<li>Delete <code>$CATALINA_BASE/conf/logging.properties</code> to
prevent java.util.logging generating zero length log files.</li>
@@ -410,7 +500,7 @@ log4j.logger.org.apache.catalina.core.Co
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>
+</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
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
