tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ma...@apache.org
Subject svn commit: r810931 - /tomcat/tc6.0.x/trunk/webapps/docs/logging.xml
Date Thu, 03 Sep 2009 13:22:11 GMT
Author: markt
Date: Thu Sep  3 13:22:10 2009
New Revision: 810931

URL: http://svn.apache.org/viewvc?rev=810931&view=rev
Log:
Port the logging documentation changes

Modified:
    tomcat/tc6.0.x/trunk/webapps/docs/logging.xml

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=810931&r1=810930&r2=810931&view=diff
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/logging.xml (original)
+++ tomcat/tc6.0.x/trunk/webapps/docs/logging.xml Thu Sep  3 13:22:10 2009
@@ -30,187 +30,107 @@
 
 <body>
 
-  <section name="Important note">
-  <p>
-    By default, only java.util.logging is available for the core Tomcat, as Tomcat uses
-    a package renamed logging implementation which is hardcoded for that logger. Usage of
-    alternate loggers is available after building or downloading the extra components
-    (see the <a href="extras.html">extras components</a> documentation), which
includes
-    a full commons-logging implementation.
-  </p>
-  </section>
-  
   <section name="Introduction">
-  <p>
-    Tomcat 6.0 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 the ability to log
-    hierarchically across various log levels without needing to rely on a particular
-    logging implementation.
-  </p>
-  <p>
-    An important consequence for Tomcat 6.0 is that the &lt;Logger&gt; element found
in 
-    previous versions to create a <code>localhost_log</code> is no longer a valid
nested element 
-    of &lt;Context&gt;. Instead, the default Tomcat configuration will use java.util.logging.

-    If the developer wishes to collect detailed internal Tomcat logging (i.e what is happening

-    within the Tomcat engine), then they should configure a logging system such as java.util.logging

-    or log4j as detailed next.
-  </p>
-
-  </section>
-
-  <section name="log4j">
     <p>
-      Tomcat 6.0 has done away with <code>localhost_log</code> which you may
be familiar with
-      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.
+      Tomcat 6.0 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.
     </p>
 
     <p>
-      If you need to setup cross-context detailed logging from within Tomcat's code, 
-      then you can use a simple log4j configuration. Note that this logging can be very 
-      verbose depending on the log level you chose to use.  Note also that a log4j logging

-      configuration is not going to produce stack trace type logging: those stack traces
-      are output to <code>stdout</code> as discussed above.
+      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.
     </p>
 
     <p>
-      Follow the following steps to setup a file named tomcat.log that has internal 
-      Tomcat logging output to it:
+      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.
     </p>
 
-    <p>
-      <ol>
-        <li>Create a file called log4j.properties with the following content 
-            and save it into $CATALINA_HOME/lib.
-          <source>
-            log4j.rootLogger=debug, R <br />
-            log4j.appender.R=org.apache.log4j.RollingFileAppender <br />
-            log4j.appender.R.File=${catalina.home}/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 <br />
-            log4j.logger.org.apache.catalina=DEBUG, R
-          </source>
-	</li>
-
-	<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>
-
-        <li>Place <code>output/extras/tomcat-juli-adapters.jar</code> in

-        $CATALINA_HOME/lib.</li>
-
-	<li>Start Tomcat</li>
-      </ol>
-    </p>
-
-    <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.  DEBUG level is specified which will result in the 
-      most verbose output from Tomcat.
-    </p>
-	
-    <p>
-      You can (and should) be more picky about which packages to include 
-      in the logging. Tomcat 6 defines loggers by Engine and Host names.
-      For example, for a default Catalina localhost log, add this to the
-      end of the log4j.properties above. Note that there are known issues with 
-      using this naming convention (with square brackets) in log4j XML based
-      configuration files, so we recommend you use a properties file as described
-      until a future version of log4j allows this convention.
-      
-      <ul>
-        <li>log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost]=DEBUG,
R</li>
-	<li>log4j.logger.org.apache.catalina.core=DEBUG, R</li>
-	<li>log4j.logger.org.apache.catalina.session=DEBUG, R</li>
-      </ul>
-
-      Be warned a level of DEBUG will produce megabytes of logging and slow startup
-      of Tomcat. This level should be used sparingly when debugging of internal Tomcat
-      operations is required.
-    </p>
-	
-    <p>
-      Your web applications should certainly use their own log4j configuration. 
-      This is valid <i>with</i> the above configuration.  You would place a similar
log4j.properties 
-      file in your web application's WEB-INF/classes folder, and log4j1.2.8.jar into
-      WEB-INF/lib. Then specify your package level logging. This is a basic setup of log4j

-      which does *not* require Commons-Logging, 
-      and you should consult the 
-      <a href="http://logging.apache.org/log4j/docs/documentation.html">log4j documentation</a>

-      for more options.  This page is intended only as a bootstrapping guide.
-    </p>
-	
   </section>
 
   <section name="java.util.logging">
 
   <p>
-    The default implementation of java.util.logging provided in the JDK is too limited to
be 
-    useful. A limitation of JDK Logging appears to be the inability to have per-web application
logging, 
-    as the configuration is per-VM. As a result, Tomcat will, in the default configuration,
-    replace the default LogManager implementation with a container friendly implementation
-    called JULI, which addresses these shortcomings. It supports the same configuration mechanisms

-    as the standard JDK java.util.logging, using either a programmatic approach, or properties
-    files. The main difference is that per-classloader properties files can be set (which
enables easy
-    redeployment friendly webapp configuration), and the properties files support slightly
extended
-    constructs which allows more freedom for defining handlers and assigning them to loggers.
+    The default implementation of java.util.logging provided in the JDK is too
+    limited to be useful. A limitation of JDK Logging appears to be the
+    inability to have per-web application logging,  as the configuration is
+    per-VM. As a result, Tomcat will, in the default configuration, replace the
+    default LogManager implementation with a container friendly implementation
+    called JULI, which addresses these shortcomings. It supports the same
+    configuration mechanisms as the standard JDK java.util.logging, using either
+    a programmatic approach, or properties files. The main difference is that
+    per-classloader properties files can be set (which enables easy redeployment
+    friendly webapp configuration), and the properties files support slightly
+    extended constructs which allows more freedom for defining handlers and
+    assigning them to loggers.
   </p>
   <p>
-    JULI is enabled by default in Tomcat 6.0, and supports per classloader configuration,
in addition to 
-    the regular global java.util.logging configuration. This means that logging can be configured
at 
-    the following layers:
+    JULI is enabled by default in Tomcat 6.0, and supports per classloader
+    configuration, in 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 
+      <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
+      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>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>
     </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 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.
   </p>
   <p>
     <source>org.apache.catalina.level=FINEST</source>
   </p>
   <p>
-    The configuration used by JULI is extremely similar, but uses a few extensions to allow
better 
-    flexibility in assigning loggers. The main differences are:
+    The configuration used by JULI is extremely similar, but uses a few
+    extensions to allow better flexibility in assigning loggers. The main
+    differences are:
     <ul>
-      <li>A prefix may be added to handler names, so that multiple handlers of a 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 5.0, 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 <code>.handlers</code>
property.</li>
-      <li>System property replacement for property values which start with ${systemPropertyName}.</li>
+      <li>A prefix may be added to handler names, so that multiple handlers of a
+      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
+      <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
+      <code>.handlers</code> property.</li>
+      <li>System property replacement for property values which start with
+      ${systemPropertyName}.</li>
     </ul>
   </p>
   <p>
@@ -273,8 +193,8 @@
     </p>
     
     <p>
-      Example logging.properties for the servlet-examples web application to be placed
-      in WEB-INF/classes inside the web application:
+      Example logging.properties for the servlet-examples web application to be
+      placed in WEB-INF/classes inside the web application:
       <source>
 handlers = org.apache.juli.FileHandler, java.util.logging.ConsoleHandler
 
@@ -294,5 +214,87 @@
 
   </section>
 
+  <section name="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
+      describe configuring log4j to output Tomcat's internal logging to a file
+      named tomcat.log.
+    </p>
+
+    <p>
+      <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.home}/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>
+
+        <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>
+
+        <li>Place <code>output/extras/tomcat-juli-adapters.jar</code> in

+            $CATALINA_HOME/lib.</li>
+
+        <li>Start Tomcat</li>
+      </ol>
+    </p>
+
+    <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.
+    </p>
+        
+    <p>
+      You can (and should) be more picky about which packages to include 
+      in the logging. Tomcat 6 defines loggers by Engine and Host names.
+      For example, for a more detailed Catalina localhost log, add this to the
+      end of the log4j.properties above. Note that there are known issues with 
+      using this naming convention (with square brackets) in log4j XML based
+      configuration files, so we recommend you use a properties file as
+      described until a future version of log4j allows this convention.
+      
+      <source>
+        log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost]=DEBUG<br
/>
+        log4j.logger.org.apache.catalina.core=DEBUG<br />
+        log4j.logger.org.apache.catalina.session=DEBUG<br />
+      </source>
+
+      Be warned a level of DEBUG will produce megabytes of logging and slow
+      startup of Tomcat. This level should be used sparingly when debugging of
+      internal Tomcat operations is required.
+    </p>
+        
+    <p>
+      Your web applications should certainly use their own log4j configuration. 
+      This is valid <i>with</i> the above configuration.  You would place a
+      similar log4j.properties file in your web application's WEB-INF/classes
+      directory, and log4jx.y.z.jar into WEB-INF/lib. Then specify your package
+      level logging. This is a basic setup of log4j which does *not* require
+      Commons-Logging, and you should consult the 
+      <a href="http://logging.apache.org/log4j/docs/documentation.html">log4j
+      documentation</a> for more options. This page is intended only as a
+      bootstrapping guide.
+    </p>
+        
+  </section>
+
 </body>
 </document>



---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org


Mime
View raw message