8.6 Configuring Logging

You can configure logging to troubleshoot errors or to receive notification for specific events. For example, configure logging to perform the following activities:

  • Stop recording of Debug and Info messages in the log file.

  • Allow recording of Info level messages from the HTTP subsystem in the log file.

  • Configure an appender to publish messages only whose severity level is Warning or higher.

  • Track log information for individual servers in a cluster.

You may need to configure the logging.properties file in some cases.

The following sections describe basic configuration tasks:

8.6.1 Understanding Logging Configuration

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.

8.6.2 Understanding the Log Level Settings

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:

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

Change the priority value to:

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

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

8.6.3 Specifying the Severity Level for Commons Logging API Loggers

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:

  • In Identity Manager Dashboard, go to Configuration > Logging and change the log level settings. The changes will be immediately applied. When you restart Identity Applications, the changes are not preserved. To persist the changes for subsequent sessions, select Persist the logging changes. Alternatively, modify the log4j.properties file.

  • Edit the log4j.properties file. Your changes will take effect when you restart the User Application. Identity Applications preserves this configuration for subsequent sessions.

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

8.6.4 Configuring Logging Settings in Identity Manager Dashboard

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

  • Add a new logger for a class or package name. For more information, click in Identity Manager Dashboard.

  • Remove a logger for a class or package name. For more information, click in Identity Manager Dashboard.

  • Set the logging level (Fatal, Error, Warn, Info, Debug, Trace) for each class or package name.

  • Reset all logging levels.

All logging configuration cannot be changed in the Logging 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.

You can change the log level of the packages individually by searching a package name. If you want to change the log level for all the packages:

  1. Select Change log level for the listed packages.

  2. Select the log level from the list.

    Table 8-3 Types of Log Levels




    The least detail. Writes fatal errors to the log.


    Writes errors that can cause system processing to not proceed.


    Logs potential failures, but the impact on execution is minimal. Warnings indicate that you should be aware that this event is happening and might want to make a configuration change to avoid it.


    Logs informational messages. No execution or data impact occurred.


    Includes debugging information.


    The most detail. Writes tracing information (plus all of the above) to the log.

    NOTE:By default, the log level is set to Info for all the packages.

  3. (Conditional) To retain these changes after restarting the application server, select Persist the logging changes.

  4. Click Apply.

NOTE:The portal functionality and export or import of portal content within the User Application is discontinued from this release. If you have the packages corresponding to these features, manually remove the packages from the idmuserapp_logging.xml file.

8.6.5 Editing the log4j Files

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.

NOTE:The Console and File appenders are defined in tomcat-log4j.xml. The NAudit appender that is specific to the identity applications is defined in idmuserapp_logging.xml. All loggers specific to the identity applications are defined in idmuserapp_logging.xml.

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:

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

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:

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

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.

8.6.6 Managing Log File Size

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

  • The system console of the application server where the identity applications components are deployed

  • A log file on that Tomcat server. For example: /opt/netiq/idm/apps/tomcat/logs/catalina.out

    This is a rolling log file. By default, the server rotates the file based on a time interval of 24 hours. However, you can instruct the server to rotate the file over to another file after it reaches a certain size by specifying the size in the log4j.appender.R.MaxFileSize property in the $TOMCAT_HOME/lib/log4j.properties file. It does not rotate the local server log file when you start the server.

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.