From 0336547783a388bb588dba0c713abfe96c68d8de Mon Sep 17 00:00:00 2001
From: kkolinko <kkolinko@13f79535-47bb-0310-9956-ffa450edef68>
Date: Fri, 18 Mar 2011 15:22:08 +0000
Subject: [PATCH] Improve the logging documentation

git-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@1082948 13f79535-47bb-0310-9956-ffa450edef68
---
 webapps/docs/changelog.xml |   5 +-
 webapps/docs/logging.xml   | 156 +++++++++++++++++++++++++++++++--------------
 2 files changed, 111 insertions(+), 50 deletions(-)

diff --git a/webapps/docs/changelog.xml b/webapps/docs/changelog.xml
index 730734a1f..f9d14ac03 100644
--- a/webapps/docs/changelog.xml
+++ b/webapps/docs/changelog.xml
@@ -74,7 +74,7 @@
         client sends multiple JSESSIONID cookies. (markt)
       </fix>
       <fix>
-        <bug>50929</bug>When wrapping an exception, include the root cause.
+        <bug>50929</bug>: When wrapping an exception, include the root cause.
         Patch provided by sebb. (markt) 
       </fix>
     </changelog>
@@ -115,6 +115,9 @@
         <bug>50925</bug>: Update SSL how-to to take account of
         <code>keyPass</code> connector attribute. (markt)
       </fix>
+      <update>
+        Improve Tomcat Logging documentation. (kkolinko)
+      </update>
     </changelog>
   </subsection>
   <subsection name="Other">
diff --git a/webapps/docs/logging.xml b/webapps/docs/logging.xml
index 0eb2c7931..c8a396f7b 100644
--- a/webapps/docs/logging.xml
+++ b/webapps/docs/logging.xml
@@ -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 the 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,15 +96,33 @@
       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.
-      More details about Tomcat JULI may be found below.
     </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 and in Tomcat Javadoc
+      for the <a href="api/org/apache/juli/package-summary.html"><code>org.apache.juli</code></a>
+      package.
+    </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
       logged to the category named
@@ -114,34 +134,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 +167,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,35 +225,42 @@
     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>
@@ -214,23 +268,27 @@
       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>As in Java 6.0, loggers can define a list of handlers using the
+      <li>System property replacement is performed for property values which
+      contain ${systemPropertyName}.</li>
+      <li>As in Java 6, 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
-      <code>bufferSize</code> property of a handler. A value of <code>0</code>
+      <li>Several additional implementations of <code>java.util.logging.Handler</code>,
+      that can be used together with the ones provided by Java.
+      The notable one is <code>org.apache.juli.FileHandler</code></li>
+      <li><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. The value of <code>0</code>
       uses system default buffering (typically an 8K buffer will be used). A
       value of <code>&lt;0</code> forces a writer flush upon each log write. A
       value <code>&gt;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>
   </p>
   <p>
-- 
2.11.0