Configuring Logging for tc Server

As with standard Apache Tomcat, SpringSource tc Server uses Commons Logging throughout its internal code which in turn allows you to choose a logging configuration that suits your needs, such as java.util.logging (configured by default) or log4j. Commons Logging provides tc Server with the ability to log hierarchially across various log levels without needing to rely on a particular logging implementation.

This section provides an overview of the basic information in the standard Apache Tomcat logging documentation (see Logging in Tomcat.) This section also describes the additional logging features of tc Server as compared to the default logging in Apache Tomcat, such as asynchronous logging. The section is broken up into the following conceptual topics:

Configuring the JULI Implemenation of java.util.logging

SpringSource tc Server provides its own implementation of java.util.logging called JULI that addresses one of the biggest limitation of the implementation provided by the JDK: the inability to configure per-Web application logging. The JULI implementation is the default logging framework in tc Server.

Note: It is assumed that you are already familiar with the basic java.util.logging facility provided by the JDK; if this is not the case, see:

With the JULI implementation, you can configure logging at a variety of levels:

As noted above, at each level you use a logging.properties file to configure logging; the level that the file configures is based on the location of the file. You can also configure logging programmatically, although this document does not discuss this method. The logging.properties files for the tc Server instance or Web application, however, support extended constructs that allow more freedom to define handlers and assign them to loggers. The differences are described later in this section.

The default tc Server logging.properties file, located in CATALINA_BASE/conf of your server instance, specifies two types of handlers: ConsoleHandler for routing logging to stdout and FileHandler for writing long messages to a file. You can set the log level of each handler to standard java.util.logging levels, such as SEVERE, WARNING, etc; see Logging Levels for java.util.logging for the full list.

The default log level setting in the JDK logging.properties file is set to INFO. You can also target specific packages from which to collect logging and specify the level of logging you want. For example, to set debugging from the entire tc Server instance, add the following to the CATALINA_BASE/conf/logging.properties file:

 org.apache.catalina.level=FINEST

If you set the preceding log level, you must also ensure that the ConsoleHandler's level is set to to collect this threshold, or in other words, be at a level higher than the overall tc Server level.

When you configure the logging.properties file for the tc Server instance or Web application, you use a similar configuration as that of the JDK logging.properties file. You can also specify additional extensions to allow better flexibility in assigning loggers. Use the following guidelines:

The following example shows a CATALINA_BASE/conf/logging.properties file for a tc Server instance. It shows how to use the level, prefix, directory, and bufferSize properties for a variety of FileHandlers:

handlers = 1catalina.org.apache.juli.FileHandler, \
           2localhost.org.apache.juli.FileHandler, \
           3manager.org.apache.juli.FileHandler, \
           4admin.org.apache.juli.FileHandler, \
           java.util.logging.ConsoleHandler

.handlers = 1catalina.org.apache.juli.FileHandler, java.util.logging.ConsoleHandler

############################################################
# Handler specific properties.
# Describes specific configuration info for Handlers.
############################################################

1catalina.org.apache.juli.FileHandler.level = FINE
1catalina.org.apache.juli.FileHandler.directory = ${catalina.base}/logs
1catalina.org.apache.juli.FileHandler.prefix = catalina.

2localhost.org.apache.juli.FileHandler.level = FINE
2localhost.org.apache.juli.FileHandler.directory = ${catalina.base}/logs
2localhost.org.apache.juli.FileHandler.prefix = localhost.

3manager.org.apache.juli.FileHandler.level = FINE
3manager.org.apache.juli.FileHandler.directory = ${catalina.base}/logs
3manager.org.apache.juli.FileHandler.prefix = manager.

4admin.org.apache.juli.FileHandler.level = FINE
4admin.org.apache.juli.FileHandler.directory = ${catalina.base}/logs
4admin.org.apache.juli.FileHandler.prefix = admin.
4admin.org.apache.juli.FileHandler.bufferSize = 16384

java.util.logging.ConsoleHandler.level = FINE
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter


############################################################
# Facility specific properties.
# Provides extra control for each logger.
############################################################

org.apache.catalina.core.ContainerBase.[Catalina].[localhost].level = INFO
org.apache.catalina.core.ContainerBase.[Catalina].[localhost].handlers = \
   2localhost.org.apache.juli.FileHandler

org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/manager].level = INFO
org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/manager].handlers = \
   3manager.org.apache.juli.FileHandler

org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/admin].level = INFO
org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/admin].handlers = \
   4admin.org.apache.juli.FileHandler

The following example shows a WEB-INF/classes/logging.properties file for a specific Web application. The properties file configures a ConsoleHandler to route messages to stdout. IT also configures a FileHandler that prints log messages at the FINE level to the CATALINA_BASE/logs/servlet-examples.log file:

handlers = org.apache.juli.FileHandler, java.util.logging.ConsoleHandler

############################################################
# Handler specific properties.
# Describes specific configuration info for Handlers.
############################################################

org.apache.juli.FileHandler.level = FINE
org.apache.juli.FileHandler.directory = ${catalina.base}/logs
org.apache.juli.FileHandler.prefix = servlet-examples.

java.util.logging.ConsoleHandler.level = FINE
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

Logging Levels for java.util.logging

The following table lists the standard log levels that you can set in the various logging.properties files, with the highest level listed first down to the lowest level (OFF). Enabling logging at a given level also enables logging at all higher levels. In general, the lower level of logging you enable, the more data that tc Server writes to the log files, so be careful when setting the logging level very low.

Level Description
ALL Specifies that all messages should be logged.
SEVERE Specifies a message level indicating a serious failure.

In general, SEVERE messages should describe events that are of considerable importance and which will prevent normal program execution. They should be reasonably intelligible to end users and to system administrators.

WARNING Specifies a message level indicating a potential problem.

In general, WARNING messages should describe events that will be of interest to end users or system managers, or that indicate potential problems.

INFO Specifies a message level for informational messages.

Typically, INFO messages will be written to the console or its equivalent, which means that the INFO level should only be used for reasonably significant messages that will make sense to end users and system admins.

CONFIG Specifies a message level for static configuration messages.

CONFIG messages are intended to provide a variety of static configuration information, to assist in debugging problems that may be associated with particular configurations. For example, CONFIG message might include the CPU type, the graphics depth, the GUI look-and-feel, etc.

FINE Use the FINE, FINER, and FINEST levels for relatively detailed tracing. The exact meaning of the three levels vary between subsystems, but in general, FINEST should be used for the most voluminous detailed output, FINER for somewhat less detailed output, and FINE for the lowest volume (and most important) messages.

In general the FINE level should be used for information that will be broadly interesting to developers who do not have a specialized interest in the specific subsystem.

FINE messages might include things like minor (recoverable) failures. Issues indicating potential performance problems are also worth logging as FINE.

FINER Use the FINE, FINER, and FINEST levels for relatively detailed tracing. The exact meaning of the three levels vary between subsystems, but in general, FINEST should be used for the most voluminous detailed output, FINER for somewhat less detailed output, and FINE for the lowest volume (and most important) messages.

FINER indicates a fairly detailed tracing message. By default logging calls for entering, returning, or throwing an exception are traced at this level.

FINEST Use the FINE, FINER, and FINEST levels for relatively detailed tracing. The exact meaning of the three levels vary between subsystems, but in general, FINEST should be used for the most voluminous detailed output, FINER for somewhat less detailed output, and FINE for the lowest volume (and most important) messages.

FINEST indicates a highly detailed tracing message.

OFF Specifies that logging should be turned off.

Configuring Asynchronous Logging

By default, the tc Server thread that handles incoming Web requests is the same thread that writes to the log file, such as catalina.out. This means that if there is some sort of resource issue causing the thread writing to log file to block, the incoming Web request is also blocked until the thread is able to finish writing to the log file. Depending on what is going on with your environment, this could impact the performance of incoming Web requests.

Asynchronous logging addresses this potential performance problem by having a separate thread write to the log file. This means that the Web request thread does not have to wait for the write to the log file to complete, and incoming request from users (or Web services) are not affected by internal resource issues.

Another advantage of asynchronous logging is that you can configure a more verbose log level without affecting the performance of the incoming requests, because even though a lot of information is being written to the log file, it is being written by a different thread from the one handling the incoming requests.

Note that asynchronous logging is available only if your tc Server instance uses version 1.6 of the JDK/JRE. Also, asynchronous logging is available only with the java.util.logging logging configuration, and not with log4j.

The following procedure describes how to configure asynchronous logging for a tc Server instance.

  1. Open the CATALINA_BASE/conf/logging.properties file for editing, where CATALINA_BASE refers to the root directory of your tc Server instance, such as /home/tcserver/tcServer-6.0/myserver. Then change ever instance of FileHandler in the file with AsyncFileHandler.

    The following snippet shows how the first few non-commented lines of the file will look after the substitution:

    handlers = 1catalina.org.apache.juli.AsyncFileHandler, \
               2localhost.org.apache.juli.AsyncFileHandler, \
               3manager.org.apache.juli.AsyncFileHandler, \
               4host-manager.org.apache.juli.AsyncFileHandler, \
               java.util.logging.ConsoleHandler
    
    .handlers = 1catalina.org.apache.juli.AsyncFileHandler
    
    ############################################################
    # Handler specific properties.
    # Describes specific configuration info for Handlers.
    ############################################################
    
    1catalina.org.apache.juli.AsyncFileHandler.level = FINE
    1catalina.org.apache.juli.AsyncFileHandler.directory = ${catalina.base}/logs
    1catalina.org.apache.juli.AsyncFileHandler.prefix = catalina.
    
    2localhost.org.apache.juli.AsyncFileHandler.level = FINE
    2localhost.org.apache.juli.AsyncFileHandler.directory = ${catalina.base}/logs
    2localhost.org.apache.juli.AsyncFileHandler.prefix = localhost.
    ...
  2. Optionally configure how asynchronous logging behaves by setting one or more of the system properties listed in the properties table. Each property has a default value so you only need to set them if their default values are not adequate.

    Set the properties in the CATALINA_BASE/bin/setenv.sh (Unix) or CATALINA_BASE/bin/setenv.bat (Windows) file by updating the APPLICATION_OPTS variable. Use the standard -D option for each system property you set. The following example shows how to set two of the properties on Unix:

    APPLICATION_OPTS=-Dorg.apache.juli.AsyncOverflowDropType=1 -Dorg.apache.juli.AsyncMaxRecordCount=10000
  3. Restart your tc Server instance for the changes to take effect.

Asychronous Logging System Properties

The following table lists the system properties you can set to configure the asychronous logging feature of tc Server.

Property Name Description Default Value
org.apache.juli.AsyncOverflowDropType Specifies the action taken by tc Server when the memory limit of records has been reached. You can set this property to one of the following values:
  • 1 : Specifies that tc Server drop, and not log, the record that caused the overflow.
  • 2 : Specifies that tc Server drop the record that is next in line to be logged to make room for the latest record on the queue.
  • 3 : Specifies that tc Server suspend the thread while the queue empties out and flushes the entries to the write buffer.
  • 4 : Specifies that tc Server drop the current log entry.
1
org.apache.juli.AsyncMaxRecordCount Specifies the max number of log records that the asychronous logger keeps in memory. When this limit is reached and a new record is being logged by the JULI framework, the system takes an action based on the value of the org.apache.juli.AsyncOverflowDropType property.

This number represents the global number of records, not on a per handler basis.

10000
org.apache.juli.AsyncLoggerPollInterval Specifies the poll interval (in milliseconds) of the asynchronous logger thread. If the log queue is empty, the asynchronous logging thread issues a poll(poll_interval) call in order to not wake up to often. 1000

Configuring log4j

The following steps describe how to configure basic log4j, rather than java.util.logging, as the logging implementation for a given tc Server instance. The text after the basic procedure describes how to further customize the log4j configuration.

  1. Create, if they do not already exist, the following directories under the CATALINA_BASE directory, which is the root directory of your tc Server instance, such as /home/tcserver/tcServer-6.0/myserver:

    • CATALINA_BASE/lib
    • CATALINA_BASE/bin
  2. Create a file called log4j.properties in the CATALINA_BASE/lib directory of your tc Server instance

  3. Add the following properties to the log4j.properties file:

    log4j.rootLogger=INFO, R 
    log4j.appender.R=org.apache.log4j.RollingFileAppender
    log4j.appender.R.File=${catalina.base}/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
  4. Download log4j (version 1.2 or later) and place the log4j.jar file in the CATALINA_BASE/lib directory of your tc Server instance.

  5. Build the additional logging components that you will need to replace the default java.util.logging JULI implementation. See Additional Components for details.

    This build process puts the components in the output/extras sub-directory of the directory in which you ran the ant script.

  6. Copy the output/extras/tomcat-juli.jar file that you built in the preceding step to the CATALINA_BASE/bin directory of your tc Server instance.

  7. Copy the output/extras/tomcat-juli-adpaters.jar file that you built in the preceding step to the CATALINA_BASE/lib directory of your tc Server instance.

  8. Delete the CATALINA_BASE/conf/logging.properties file to prevent java.util.properties from generating zero-length log files.

Specifying Included Packages With log4j Logging

SpringSource recommends that you configure the specifc packages that you want to include in the logging. Because tc Server defines loggers by Engine and Host names, use these names in the log4j.properties file.

For example, if you want a more detailed Catalina localhost log, add the following lines to the end of the log4j.properties you created:

log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost]=DEBUG
log4j.logger.org.apache.catalina.core=DEBUG
log4j.logger.org.apache.catalina.session=DEBUG

Warning: A level of DEBUG will produce megabytes of logging and will consequently slow the startup of tc Server. Be sure that you use this level sparingly, typically only when you need to debug internal tc Server operations.

For the full list of logging levels you can specify when configuring log4j, see Log Levels.

Configuring a Web Application with log4j Logging

You can configure your Web applications to use log4j for their own logging, which is in addition to the tc Server logging configuration described in the preceding sections.

The basic steps are as follows:

  1. Create a log4j.properties that is similar to the one described in Configuring log4j.
  2. Update the log4j.properties file with logging information specific to your application. For example, if you want to specify that the logger in package my.package be at level DEBUG, add the following:
    log4j.logger.my.package=DEBUG
  3. Put the log4j-version.jar file in the WEB-INF/lib directory of your Web application, where version refers to the version of the JAR file, such as log4j-1.2.15.jar.

See the log4j documenation for detailed information>.