tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From yo...@apache.org
Subject cvs commit: jakarta-tomcat-catalina/webapps/docs changelog.xml logging.xml
Date Fri, 19 Nov 2004 15:38:37 GMT
yoavs       2004/11/19 07:38:37

  Modified:    webapps/docs changelog.xml logging.xml
  Log:
  Bugzilla 32249: Updated logging documentation
  
  Revision  Changes    Path
  1.175     +3 -0      jakarta-tomcat-catalina/webapps/docs/changelog.xml
  
  Index: changelog.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tomcat-catalina/webapps/docs/changelog.xml,v
  retrieving revision 1.174
  retrieving revision 1.175
  diff -u -r1.174 -r1.175
  --- changelog.xml	19 Nov 2004 15:07:39 -0000	1.174
  +++ changelog.xml	19 Nov 2004 15:38:36 -0000	1.175
  @@ -38,6 +38,9 @@
         <update>
           <bug>22679</bug>: Added misc note on accessing session ID to SSL-HowTo.
(yoavs)
         </update>
  +      <update>
  +        <bug>32249</bug>: Updated logging documentation. (yoavs)
  +      </update>
       </changelog>
     </subsection>
   
  
  
  
  1.4       +121 -57   jakarta-tomcat-catalina/webapps/docs/logging.xml
  
  Index: logging.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tomcat-catalina/webapps/docs/logging.xml,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- logging.xml	17 Nov 2004 10:35:29 -0000	1.3
  +++ logging.xml	19 Nov 2004 15:38:36 -0000	1.4
  @@ -9,76 +9,140 @@
     <properties>
       <title>Logging in Tomcat</title>
       <author>Allistair Crossley</author>
  +    <author email="yoavs@apache.org">Yoav Shapira</author>
     </properties>
   
   <body>
   
     <section name="Introduction">
  -  </section>
  +  <p>
  +    Tomcat 5.5 uses 
  +    <a href="http://jakarta.apache.org/commons/logging">Commons Logging</a>
  +    throughout its internal code allowing the 
  +    developer to choose a logging configuration that suits their needs, e.g
  +    JDK Logging or 
  +    <a href="http://logging.apache.org/log4j">Log4J</a>. 
  +    Commons Logging provides Tomcat the ability to log
  +    hierarchially across various log levels without needing to rely on a particular
  +    logging implementation.
  +  </p>
  +  <p>
  +    An important consequence for Tomcat 5.5 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, <code>stdout</code> will collect runtime
exceptions and other uncaught
  +    exception generated by web applications. 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 JDK Logging or log4j as detailed next.
  +  </p>
   
  -  <section name="java.util.logging">
     </section>
   
     <section name="log4j">
       <p>
  -      	Tomcat 5.5 has done away with localhost_log 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 stdout log.
  -	</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 van 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, that is output to
  -		stdout as discussed.
  -	</p>
  -
  -	<p>Follow the following steps to setup a file named tomcat.log that has internal
Tomcat logging output to it.</p>
  -
  -	<ol>
  -		<li>
  -			Create a file called log4j.properties with the following content and save it into common/classes.

  -			Use the appropriate file path convention for your OS, here is is Windows, and example
*nix path may be
  -			/var/jakarta-tomcat-5.5.4/logs/tomcat.log
  -<source>
  -log4j.rootLogger=debug, R
  -log4j.appender.R=org.apache.log4j.RollingFileAppender
  -log4j.appender.R.File=d:/jakarta-tomcat-5.5.4/logs/tomcat.log
  -log4j.appender.R.MaxFileSize=10MB
  -log4j.appender.R.MaxBackupIndex=10
  -log4j.appender.R.layout=org.apache.log4j.PatternLayout
  -log4j.appender.R.layout.ConversionPattern=%p %t %c - %m%n
  -log4j.logger.org.apache.catalina=DEBUG, R</source>
  -		</li>
  -		<li><a>Acquire log4j1.2.8.jar</a> and add it into Tomcat's common/lib
folder.</li>
  -		<li>Start Tomcat</li>
  -	</ol>
  -
  -	<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. The above generated
  -		about 5MB of logging with bundled web applications and Struts web applications.
  -	</p>
  -	
  -	<p>
  -		You can of course choose to be more picky about which packages to include in the logging.
For example try substituting the
  -		last line of the above configuration with one of these:
  +      Tomcat 5.5 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.
  +    </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 van 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.
  +    </p>
  +
  +    <p>
  +      Follow the following steps to setup a file named tomcat.log that has internal 
  +      Tomcat logging output to it:
  +    </p>
  +
  +    <p>
  +      <ol>
  +        <li>Create a file called log4j.properties with the following content 
  +            and save it into common/classes. </li>
  +	<li>Use the appropriate file path convention for your OS.  Below is
  +            a Window example, which on *nix might be
  +	    <code>/var/jakarta-tomcat-5.5.4/logs/tomcat.log</code>.</li>
  +        <li>
  +          <source>
  +            log4j.rootLogger=debug, R <br />
  +            log4j.appender.R=org.apache.log4j.RollingFileAppender <br />
  +            log4j.appender.R.File=d:/jakarta-tomcat-5.5.4/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/common/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>
   	
  -		<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>
  -	</p>
  +    <p>
  +      You can (and should) be more picky about which packages to include 
  +      in the logging. For example try substituting the
  +      last line of the above configuration with one of these:
  +      
  +      <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>
  +    </p>
   	
  -	<p>The usefulness of what you will find from the log4j logging is debatable and
will depend on your needs. Your
  -		web applications should certainly use their own log4j configuration. This is valid <i>with</i>
the above.
  -		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
and you should consult the log4j
  -		documentation for more options, but hopefully this section will get you up to a basic
speed.
  -	</p>
  +    <p>
  +      Your web applications should certainly use their own log4j configuration. 
  +      This is valid <i>with</i> the above.  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

  +      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>
  +    In order to configure JDK logging you should have JDK 1.4+. Tomcat 5.5 is intended
for
  +    JDK 5.0, but can be run on JDK 1.4 using a compatibility package.
  +  </p>
  +  <p>
  +    In order to configure JDK Logging, you should find the JDK's logging.properties file.
Check
  +    your JAVA_HOME environment setting to see which JDK Tomcat is using (or maybe JRE 5.0
as Tomcat
  +    can now run on a JRE from version 5.5). The file will be in <code>$JAVA_HOME/jre/lib</code>.
  +  </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, CONFIG,
INFO, 
  +    WARN, FINE, 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.
  +  </p>
  +  <p>
  +    <source>org.apache.catalina.level=FINEST</source>
  +  </p>
  +
  +  <p>
  +    A limitation of JDK Logging appears to be the inability to have per-web application
logging, 
  +    as the configuration is per-VM. It is advisable to use log4j for per-web application
logging
  +    as explained below.
  +  </p>
  +
     </section>
   
   </body>
  
  
  

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


Mime
View raw message