From: kkolinko Date: Tue, 16 Nov 2010 02:54:12 +0000 (+0000) Subject: Improve logging documentation. X-Git-Url: https://git.internetallee.de/?a=commitdiff_plain;h=0d8f9e8dce1a1f3a8146454f4ca945be7d19ca73;p=tomcat7.0 Improve logging documentation. I completely rewrote the "Introduction" section of the page, to provide a lot more of details. git-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@1035518 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/webapps/docs/changelog.xml b/webapps/docs/changelog.xml index 768ed21d4..a05c66ec3 100644 --- a/webapps/docs/changelog.xml +++ b/webapps/docs/changelog.xml @@ -234,6 +234,9 @@ distributed Manager implementations to report full session information through the HTML Manager. (markt) + + Improve Tomcat Logging documentation. (kkolinko) + diff --git a/webapps/docs/logging.xml b/webapps/docs/logging.xml index 10d94b6a5..0eb2c7931 100644 --- a/webapps/docs/logging.xml +++ b/webapps/docs/logging.xml @@ -36,30 +36,123 @@

- Tomcat uses + Logging in Apache Tomcat is implemented with the help of Apache Commons Logging - 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.

- 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 - extras 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 java.util.logging framework.

- 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 file (catalina.out). + 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 extras + component. Instructions on how to configure Tomcat to use Log4j framework + for its internal logging may be found below. +

+ +

+ A web application running on Apache Tomcat can: +

+
    +
  • + Use logging API provided by the Java Servlets specification, + javax.servlet.ServletContext.log(...) +
    • +
  • + Use system logging API, java.util.logging. +
    • +
  • + Use any logging framework of its choice. +
    • +
+ +

+ The logging frameworks used by different web applications run independently + of each other. See class loading + for more details. + The exception to this rule is java.util.logging, 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. +

+ +

+ Apache Tomcat has its own implementation of several key elements of + java.util.logging 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 java.util.logging 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. +

+ +

+ The calls to javax.servlet.ServletContext.log(...) to write + log messages are handled by internal Tomcat logging. Such messages are + logged to the category named +

+ org.apache.catalina.core.ContainerBase.[${engine}].[${host}].[${context}] +

+ This logging is performed according to the Tomcat logging configuration. You + cannot overwrite it in a web application. +

+ +

+ Old applications that still use System.out or System.err + can be tricked, by setting swallowOutput attribute on a + Context. If the attribute is set to + true, calls to System.out/err during request + processing will be intercepted, and their output will be fed to the + logging subsystem using the + javax.servlet.ServletContext.log(...) calls.
+ Note, that this feature is actually a trick, + and works only with direct calls to System.out/err, + 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 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 catalina.out. The name is configurable + using an environment variable. (See the startup scripts). + Whatever is written to System.err/out will be logged in + that file. That may include: +

+ +
    +
  • Thread dumps, if you requested them via a system signal
    • +
  • Uncaught exceptions printed by java.lang.ThreadGroup.uncaughtException(..)
    • +
+ +

+ When running as a service on Windows, the console output is also caught + and redirected, but the file names are different. +

+ +

+ A related, but different feature is access logging. It can be configured + as a valve at the Context, or Host, or Engine. See Valves + documentation for more details.