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="[EMAIL PROTECTED]">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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]

Reply via email to