tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r1042783 - in /tomcat/tc6.0.x/trunk/webapps/docs: changelog.xml logging.xml
Date Mon, 06 Dec 2010 20:38:27 GMT
Author: kkolinko
Date: Mon Dec  6 20:38:26 2010
New Revision: 1042783

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.


Modified: tomcat/tc6.0.x/trunk/webapps/docs/changelog.xml
--- 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 @@
         CVE-2010-4172: Multiple XSS in Manager application. (markt/kkolinko)
+      <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>
         <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
--- 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">
-      Tomcat uses 
-      <a href="">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="">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="">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.
-      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.
-      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
+      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.
-  <section name="java.util.logging">
+  <section name="Using java.util.logging (default)">
     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 = \
-# For example, set the 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
@@ -227,7 +315,7 @@ java.util.logging.ConsoleHandler.formatt
-  <section name="log4j">
+  <section name="Using Log4j">
       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>
-      <ol>
+    <ol>
         <li>Create a file called 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 />[Catalina].[localhost]=INFO, LOCALHOST<br
+  INFO, MANAGER<br />[Catalina].[localhost].[/host-manager]=\<br
+    <ol start="2">
         <li><a href="">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
         <li>Replace <code>$CATALINA_HOME/bin/tomcat-juli.jar</code> with
@@ -266,15 +388,13 @@ log4j.appender.R.layout.ConversionPatter
         <li>Delete <code>$CATALINA_BASE/conf/</code>
             prevent java.util.logging generating zero length log files.</li>
         <li>Start Tomcat</li>
-      </ol>
-    </p>
+    </ol>
-      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.
@@ -311,11 +431,17 @@
       If you have multiple instances of Tomcat, each with a separate
-      <code>$CATALINA_HOME</code> but a shared <code>$CATALINA_BASE</code>,
+      <code>$CATALINA_BASE</code> but a shared <code>$CATALINA_HOME</code>
       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
+      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>

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message