| <?xml version="1.0"?> |
| <!DOCTYPE document [ |
| <!ENTITY project SYSTEM "project.xml"> |
| ]> |
| <document url="logging.html"> |
| |
| &project; |
| |
| <properties> |
| <title>Logging in Tomcat</title> |
| <author>Allistair Crossley</author> |
| <author email="yoavs@apache.org">Yoav Shapira</author> |
| </properties> |
| |
| <body> |
| |
| <section name="Introduction"> |
| <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> |
| |
| <section name="log4j"> |
| <p> |
| 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> |
| <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/common/lib.</li> |
| |
| <li><a href="http://jakarta.apache.org/site/binindex.cgi#commons-logging"> |
| Download Commons Logging</a> and place the commons-logging.jar |
| (not commons-logging-api.jar) in $CATALINA_HOME/common/lib with |
| the log4j jar.</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 5.5 uses 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> |
| 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> |
| </document> |