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 <Logger> element found in + previous versions to create a <code>localhost_log</code> is no longer a valid nested element + of <Context>. 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]