Author: kkolinko
Date: Mon Dec 6 20:38:26 2010
New Revision: 1042783
URL: http://svn.apache.org/viewvc?rev=1042783&view=rev
Log:
Port logging documentation updates from TC7.
(Actually, just a copy: there is nothing TC7 specific there yet).
This includes rewritten introductory section,
Christopher Schultz's patch for log4j configuration sample,
and some other earier changes.
CTR
Modified:
tomcat/tc6.0.x/trunk/webapps/docs/changelog.xml
tomcat/tc6.0.x/trunk/webapps/docs/logging.xml
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=1042783&r1=1042782&r2=1042783&view=diff
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/changelog.xml (original)
+++ tomcat/tc6.0.x/trunk/webapps/docs/changelog.xml Mon Dec 6 20:38:26 2010
@@ -351,6 +351,14 @@
<fix>
CVE-2010-4172: Multiple XSS in Manager application. (markt/kkolinko)
</fix>
+ <update>
+ Improve Tomcat Logging documentation. (kkolinko)
+ </update>
+ <add>
+ <bug>50242</bug>: Provide a sample log4j configuration that more
+ closely matches the default JULI configuration. Patch provided by
+ Christopher Schultz. (kkolinko)
+ </add>
<add>
<bug>50294</bug>: Add more information to documentation regarding
format
of configuration files. Patch provided by Luke Meyer. (markt)
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=1042783&r1=1042782&r2=1042783&view=diff
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/logging.xml (original)
+++ tomcat/tc6.0.x/trunk/webapps/docs/logging.xml Mon Dec 6 20:38:26 2010
@@ -36,38 +36,128 @@
<section name="Introduction">
<p>
- Tomcat 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.
+ Logging in Apache Tomcat is implemented with the help of
+ <a href="http://commons.apache.org/logging";>Apache Commons Logging</a>
+ library. That library is a thin wrapper above different logging
+ frameworks. It provides Tomcat with the ability to log
+ hierarchically across various log levels without the need to rely on a
+ particular logging implementation.
</p>
<p>
- 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.
+ Since Tomcat 6.0, Tomcat uses a private package-renamed implementation of
+ Apache Commons Logging, to allow web applications to use their own
+ independent copies of the original Apache Commons Logging library.
+ In the default distribution this private copy of the library
+ is simplified and hardcoded to use the <code>java.util.logging</code>
framework.
</p>
<p>
- 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.
+ To configure Tomcat to use alternative logging frameworks for its
internal
+ logging, one has to replace the logging library with the one that is
built
+ with the full implementation. Such library is provided as an <a
href="extras.html">extras</a>
+ component. Instructions on how to configure Tomcat to use Log4j framework
+ for its internal logging may be found below.
+ </p>
+
+ <p>
+ A web application running on Apache Tomcat can:
+ </p>
+ <ul>
+ <li>
+ Use logging API provided by the Java Servlets specification,
+ <code>javax.servlet.ServletContext.log(...)</code>
+ </li>
+ <li>
+ Use system logging API, <code>java.util.logging</code>.
+ </li>
+ <li>
+ Use any logging framework of its choice.
+ </li>
+ </ul>
+
+ <p>
+ The logging frameworks used by different web applications run
independently
+ of each other. See <a href="class-loader-howto.html">class loading</a>
+ for more details.
+ The exception to this rule is <code>java.util.logging</code>, if it used
+ directly or indirectly by your logging library. That is because it is
loaded
+ by the system and is shared across web applications.
+ </p>
+
+ <p>
+ Apache Tomcat has its own implementation of several key elements of
+ <code>java.util.logging</code> API. This implementation is called "JULI".
+ The key component there is a custom LogManager implementation,
+ that is aware of different web applications running on Tomcat (and
+ their different class loaders). It supports private per-application
+ 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.
+ 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.
+ More details about Tomcat JULI may be found below.
+ </p>
+
+ <p>
+ The calls to <code>javax.servlet.ServletContext.log(...)</code> to write
+ log messages are handled by internal Tomcat logging. Such messages are
+ logged to the category named
+ </p>
+
<source>org.apache.catalina.core.ContainerBase.[${engine}].[${host}].[${context}]</source>
+ <p>
+ This logging is performed according to the Tomcat logging configuration.
You
+ cannot overwrite it in a web application.
+ </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.
+ </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.
+ When running Tomcat on unixes, the console output is usually redirected
+ to a 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
+ 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>
+ </ul>
+
+ <p>
+ When running as a service on Windows, the console output is also caught
+ and redirected, but the file names are different.
+ </p>
+
+ <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>
</section>
- <section name="java.util.logging">
+ <section name="Using java.util.logging (default)">
<p>
The default implementation of java.util.logging provided in the JDK is too
@@ -197,11 +287,9 @@ org.apache.catalina.core.ContainerBase.[
org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/admin].handlers
= \
4admin.org.apache.juli.FileHandler
-# For example, set the com.xyz.foo logger to only log SEVERE
-# messages:
-#org.apache.catalina.startup.ContextConfig.level = FINE
-#org.apache.catalina.startup.HostConfig.level = FINE
-#org.apache.catalina.session.ManagerBase.level = FINE
+# 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>
</p>
@@ -227,7 +315,7 @@ java.util.logging.ConsoleHandler.formatt
</section>
- <section name="log4j">
+ <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
@@ -235,28 +323,62 @@ java.util.logging.ConsoleHandler.formatt
named tomcat.log.
</p>
- <p>
- <ol>
+ <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.base}/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>
+ and save it into $CATALINA_HOME/lib.</li>
+ </ol>
+ <source>
+log4j.rootLogger=INFO, CATALINA
+# Define all the appenders
+log4j.appender.CATALINA=org.apache.log4j.DailyRollingFileAppender<br />
+log4j.appender.CATALINA.file=${catalina.base}/logs/catalina.<br />
+log4j.appender.CATALINA.encoding=UTF-8<br />
+# Roll-over the log once per day<br />
+log4j.appender.CATALINA.DatePattern='.'yyyy-MM-dd'.log'<br />
+log4j.appender.CATALINA.conversionPattern = %d [%t] %-5p %c- %m%n<br />
+log4j.appender.CATALINA.append=true<br />
+<br />
+log4j.appender.LOCALHOST=org.apache.log4j.DailyRollingFileAppender<br />
+log4j.appender.LOCALHOST.file=${catalina.base}/logs/localhost.<br />
+log4j.appender.LOCALHOST.encoding=UTF-8<br />
+log4j.appender.LOCALHOST.DatePattern='.'yyyy-MM-dd'.log'<br />
+log4j.appender.LOCALHOST.conversionPattern = %d [%t] %-5p %c- %m%n<br />
+log4j.appender.LOCALHOST.append=true<br />
+
+log4j.appender.MANAGER=org.apache.log4j.DailyRollingFileAppender<br />
+log4j.appender.MANAGER.file=${catalina.base}/logs/manager.<br />
+log4j.appender.MANAGER.encoding=UTF-8<br />
+log4j.appender.MANAGER.DatePattern='.'yyyy-MM-dd'.log'<br />
+log4j.appender.MANAGER.conversionPattern = %d [%t] %-5p %c- %m%n<br />
+log4j.appender.MANAGER.append=true<br />
+
+log4j.appender.HOST-MANAGER=org.apache.log4j.DailyRollingFileAppender<br />
+log4j.appender.HOST-MANAGER.file=${catalina.base}/logs/host-manager.<br />
+log4j.appender.HOST-MANAGER.encoding=UTF-8<br />
+log4j.appender.HOST-MANAGER.DatePattern='.'yyyy-MM-dd'.log'<br />
+log4j.appender.HOST-MANAGER.conversionPattern = %d [%t] %-5p %c- %m%n<br />
+log4j.appender.HOST-MANAGER.append=true<br />
+
+log4j.appender.CONSOLE=org.apache.log4j.ConsoleAppender<br />
+log4j.appender.CONSOLE.encoding=UTF-8<br />
+log4j.appender.CONSOLE.conversionPattern = %d [%t] %-5p %c- %m%n<br />
+<br />
+# Configure which loggers log to which appenders<br />
+log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost]=INFO,
LOCALHOST<br />
+log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/manager]=\<br
/>
+ INFO, MANAGER<br />
+log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/host-manager]=\<br
/>
+ INFO, HOST-MANAGER<br />
+</source>
+ <ol start="2">
<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>
@@ -266,15 +388,13 @@ log4j.appender.R.layout.ConversionPatter
<li>Delete <code>$CATALINA_BASE/conf/logging.properties</code> to
prevent java.util.logging generating zero length log files.</li>
<li>Start Tomcat</li>
- </ol>
- </p>
+ </ol>
<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.
+ This log4j configuration mirrors the default java.util.logging setup
+ that ships with Tomcat: both the manager and host-manager apps get an
+ individual log file, and everything else goes to the "catalina.log" log
+ file. Each file is rolled-over once per day.
</p>
<p>
@@ -311,11 +431,17 @@ log4j.logger.org.apache.catalina.session
<p>
If you have multiple instances of Tomcat, each with a separate
- <code>$CATALINA_HOME</code> but a shared <code>$CATALINA_BASE</code>,
then
+ <code>$CATALINA_BASE</code> but a shared <code>$CATALINA_HOME</code> then
you can configure log4j on a per instance basis by replacing references
to
<code>$CATALINA_HOME</code> in the above instructions with
- <code>$CATALINA_BASE</code>. Note that you may need to create a
- <code>$CATALINA_BASE/lib</code> directory.
+ <code>$CATALINA_BASE</code>. Note that if you do this then you may need
to
+ make some, or all, of the following additional changes:
+ <ul>
+ <li>create a <code>$CATALINA_BASE/bin</code> directory</li>
+ <li>create a <code>$CATALINA_BASE/lib</code> directory</li>
+ <li>if running with a security manager, adjust the codebase for JULI in
+ <code>$CATALINA_BASE/conf/catalina.policy</code></li>
+ </ul>
</p>
</section>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
