8.6 Configuring Logging

When you enable logging, a logging request is sent to subscribed appenders. Tomcat provides appenders for sending log messages to the standard.out file and the server log (catalina.out) file. You can control logging for each type of handler by filtering log messages based on severity level and other criteria. For example, the Stdout Handler has a Notice threshold severity level by default. Therefore, Info and Debug level messages are not sent to the standard.out file.

By default, event messages are logged to the system console and to the Tomcat server’s log file at Info logging level and above. Events are logged to all activated loggers.

The default behavior of the Tomcat server is to limit the console log4j appender to display log messages with a verbosity of Info or less. To see log messages for more verbose levels (for example, Debug), you need to examine the server log file. Notice that the low threshold settings, such as Debug are extremely verbose and will increase Tomcat's startup time.

The following sections discuss different ways of configuring the logging behavior.

Console logging involves synchronized writes. Therefore, logging can become a processor usage issue and concurrency impedance. You can change the priority value default setting to Error, on a Tomcat server, by modifying the setting in the <installdir>/Tomcat/server/IDMProv/conf/tomcat-log4j.xml file. Locate the root node that looks similar to this:

   <root>

      <priority value="INFO"/>

      <appender-ref ref="CONSOLE"/>
      <appender-ref ref="FILE"/>
   </root>

Change the priority value to:

<root>
      <priority value="ERROR"/>

      <appender-ref ref="CONSOLE"/>
      <appender-ref ref="FILE"/>
</root>

Assigning a value to the root ensures that any appenders do not have a level assigned inherit the root's level.

If you are using the Commons Logging API, logger names follow the Java package dot notation naming convention. For example, a logger name can be com.acme.Barlogger, corresponding to the name of the classes in which it is used. Each dot-separated identifier appears as a node in the Logger tree. In this case, the logger named com.acme is a parent of the logger named com.acme.Barlogger.

You can configure the severity for a package or for any logger at any level in the tree. For example, if you specify the severity level for package com.acme=Warn, then Fatal and Error messages from the child nodes of this package will be blocked. You can override the severity level of a parent node by explicitly setting a value for a child node. For example, if you specify the severity level for com.acme.Barlogger=Debug, all log messages from Barlogger will be allowed, while Fatal and Error messages will be filtered for other child nodes under com.acme.

You can specify the severity level for a package or a logger in the following ways:

If you change, enable, or disable logging, you need not restart the identity applications to apply the changes.

You can change the logging behavior of the individual packages (loggers) via the Administration tab of the User Application while the application is running. Any changes made in this way will apply only to the currently running application session and are not written to the log4j.properties file.

The Logging page shows a list of all currently defined loggers. On this page, you can:

All logging configuration cannot be changed in the Logging administration page, such as Tomcat server specific configuration and appender configuration. For making such changes, stop the identity applications and then edit the log4j.properties file.

Perform the following actions to change the logging configuration:

Identity Manager saves the logging configuration in idmuserapp_logging.xml file, located by default in the <installdir>/tomcat/server/IDMProv/conf/ directory.

The configuration settings for the identity applications logging are stored in the idmuserapp_logging.xml in the install directory on the Tomcat server. The log4j configuration settings are contained in tomcat-log4j.xml in the install directory. To configure the logging levels and other settings permanently, stop the Tomcat server and change the settings in these files.

To change the log level in the tomcat-log4j.xml file, open the file in a text editor and locate the following entry at the end of the file:

<root>
    <priority value="INFO" /> 
      <appender-ref ref="CONSOLE" /> 
      <appender-ref ref="FILE" /> 
  </root>

Assigning a value to root ensures that any log appenders that do not have a level explicitly assigned inherit the root level (in this case, Info). For example, the File appender does not have a default threshold level assigned. It assumes the root’s threshold level.

The possible log levels used by log4j are Debug, Info, Warn, Error, and Fatal, as defined in the org.apache.log4j.Level class. Inattention to the proper use of these settings can be costly in terms of performance.

A good rule of thumb is to use Info or Debug only when debugging a particular problem.

Any appender included in the root that does have a level threshold set, should set that threshold to Error, Warn, or Fatal unless you are debugging something.

The performance hit with high log levels has less to do with verbosity of messages than with the simple fact that console and file logging, in log4j, involve synchronous writes. An AsyncAppender class is available, but its use does not guarantee better performance. These are known issues of Apache log4j.

The default log level of Info in the log configuration file for the identity applications is suitable for many environments. However, for a performance intensive environment, you can change the entry as follows:

<root>
      <priority value="ERROR"/>
      <appender-ref ref="FILE"/>
</root>

For a fully tested and debugged production setup, enabling Info and Console logging are not needed. For more information about log4j, see Apache Logging Services.

By default, event messages are logged to both of the following:

To cause the immediate rotation of the log file, change the appender configuration in the log4j.properties file.

By default, the rotated files are stored in the same directory where the log file is stored. You can specify a different directory location for the archived log files in the log4j.properties file.