SpringSource tc Runtime provides its own implementation of java.util.logging called JULI that addresses a major limitation of the JDK implementation: the inability to configure per-Web application logging. The JULI implementation is the default logging framework in tc Runtime.

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

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

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 Runtime 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 Runtime 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 Runtime instance, add the following to the CATALINA_BASE/conf/logging.properties file:

 org.apache.catalina.level=FINEST

If you set the preceding log level, also set the ConsoleHandler level to collect this threshold, or in other words, be at a level higher than the overall tc Runtime level.

When you configure the logging.properties file for the tc Runtime 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 Runtime 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

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 Runtime writes to the log files, so be careful when setting the logging level very low.

By default, the tc Runtime thread that handles incoming Web requests is the same thread that writes to the log file, such as catalina.out. Thus if a resource issue causes the thread writing to the 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 your environment, this problem can affect the performance of incoming Web requests.

Asynchronous logging addresses this potential performance problem with a separate thread write to the log file. 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
	Asynchronous logging is available only if your tc Runtime 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.

To configure asynchronous logging for a tc Runtime instance:

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

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

You can use JMX to modify logging levels and other logging parameters while tc Runtime is executing. The modifications you make using JMX are not persisted; when the server restarts, any changes you made are lost. You could use this feature to enable debugging messages to help troubleshoot an application problem while the problem is occurring. This is useful for problems that take time to develop after a reboot or are otherwise difficult to reproduce.

The JULI implementation of java.util.logging allows you to create separate loggers for each Web application by adding logging.properties files to your Web applications. This allows you to control logging at a very fine level.

Using JMX, you can list loggers, change the logging level for any single logger by name, and set a new handler (log file) for a logger. You can specify the logger you want to manage using a logger string defined in the logging.properties file, prefixed with "jmx:", for example jmx:com.springsource.tcserver.

Following is code for a JSP you can use to try out using JMX to manage loggers dynamically. It reports whether different logging levels are enabled and also displays the class loader and logger names. Add the JSP to a web application, deploy it, and call it before and after changing the logging level as described in the first example below.

<%@page import="org.apache.juli.logging.*"%>
<% 
  Log log = LogFactory.getLog(this.getClass());
  String dmessage = "log.jsp log message[DEBUG] "+System.currentTimeMillis();
  String imessage = "log.jsp log message[INFO] "+System.currentTimeMillis();
  String wmessage = "log.jsp log message[WARN] "+System.currentTimeMillis();
  String emessage = "log.jsp log message[ERROR] "+System.currentTimeMillis();
  log.debug(dmessage);
  log.info(imessage);
  log.warn(wmessage);
  log.error(emessage);
%>
  Debug Enabled: <%=log.isDebugEnabled()%> <br/>  
  Info  Enabled: <%=log.isInfoEnabled()%> <br/>
  Warn  Enabled: <%=log.isWarnEnabled()%> <br/>
  Error Enabled: <%=log.isErrorEnabled()%> <br/>
  
Class Loader: <%=this.getClass().getClassLoader().getParent().
    getClass().getName()%>#<%=System.identityHashCode(this.getClass().
    getClassLoader().getParent())%> <br/>  
LoggerName: <%=this.getClass().getName()%>#<%=this.getClass().
    getClassLoader().getParent().getClass().
    getName()%>#<%=System.identityHashCode(this.getClass().
    getClassLoader().getParent())%> <br/>  

The following examples use JConsole, the Java Monitoring and Management Console included with the JDK, to manage loggers. There is a jconsole executable in the JDK bin directory that you can execute from a shell or Command Prompt. JConsole connects to a tc Runtime instance at the JMX port, 6969 by default. To verify your JMX port, check the base.jmx.port property in the CATALINA_HOME/conf/catalina.properties file.