Author: kkolinko
Date: Tue Nov 16 02:54:12 2010
New Revision: 1035518
URL: http://svn.apache.org/viewvc?rev=1035518&view=rev
Log:
Improve logging documentation.
I completely rewrote the "Introduction" section of the page, to provide a lot
more of details.
Modified:
tomcat/trunk/webapps/docs/changelog.xml
tomcat/trunk/webapps/docs/logging.xml
Modified: tomcat/trunk/webapps/docs/changelog.xml
URL:
http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/changelog.xml?rev=1035518&r1=1035517&r2=1035518&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/changelog.xml (original)
+++ tomcat/trunk/webapps/docs/changelog.xml Tue Nov 16 02:54:12 2010
@@ -234,6 +234,9 @@
distributed Manager implementations to report full session information
through the HTML Manager. (markt)
</fix>
+ <update>
+ Improve Tomcat Logging documentation. (kkolinko)
+ </update>
</changelog>
</subsection>
<subsection name="Other">
Modified: tomcat/trunk/webapps/docs/logging.xml
URL:
http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/logging.xml?rev=1035518&r1=1035517&r2=1035518&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/logging.xml (original)
+++ tomcat/trunk/webapps/docs/logging.xml Tue Nov 16 02:54:12 2010
@@ -36,30 +36,123 @@
<section name="Introduction">
<p>
- Tomcat uses
+ Logging in Apache Tomcat is implemented with the help of
<a href="http://commons.apache.org/logging";>Apache Commons Logging</a>
- throughout its internal code.
- Commons Logging provides Tomcat with the ability to log
- hierarchically across various log levels without needing to rely on 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 an
- <a href="extras.html">extras</a> component 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 file (<code>catalina.out</code>).
+ 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>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
