The Jakarta Project
      The Apache Jakarta Tomcat Servlet/JSP Container


User Guide


Tomcat Development

The Apache Jakarta Tomcat 5.5 Servlet/JSP Container

Logging in Tomcat

Printer Friendly Version

Tomcat 5.5 uses Commons Logging throughout its internal code allowing the developer to choose a logging configuration that suits their needs, e.g JDK Logging or Log4J. Commons Logging provides Tomcat the ability to log hierarchially across various log levels without needing to rely on a particular logging implementation.

An important consequence for Tomcat 5.5 is that the <Logger> element found in previous versions to create a localhost_log is no longer a valid nested element of <Context>. Instead, stdout 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.


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.

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 stdout as discussed above.

Follow the following steps to setup a file named tomcat.log that has internal Tomcat logging output to it:

  1. Create a file called with the following content and save it into common/classes.
  2.             log4j.rootLogger=debug, R 
                log4j.appender.R.layout.ConversionPattern=%p %t %c - %m%n 
      , R
  3. Download Log4J (v1.2 or later) and place the log4j jar in $CATALINA_HOME/common/lib.
  4. Download Commons Logging and place the commons-logging.jar (not commons-logging-api.jar) in $CATALINA_HOME/common/lib with the log4j jar.
  5. Start Tomcat

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.

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 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.

  •[Catalina].[localhost]=DEBUG, R
  •, R
  •, R
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.

Your web applications should certainly use their own log4j configuration. This is valid with the above configuration. You would place a similar 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 log4j documentation for more options. This page is intended only as a bootstrapping guide.


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.

In order to configure JDK Logging, you should find the JDK's 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 $JAVA_HOME/jre/lib.

The default 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 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.


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.

Copyright © 1999-2004, Apache Software Foundation