IDM

Server logs

Server logging is not the same as auditing. Auditing logs activity on the IDM system, such as access, and synchronization. Server logging records information about the internal workings of IDM, like system messages, error reporting, service loading, or startup and shutdown messaging.

Configure server logging in your project’s conf/logging.properties file. Changes to logging settings require a server restart before they take effect. Alternatively, use JMX via jconsole to change the logging settings. In this case, changes take effect without restarting the server.

Log message handlers

The way IDM logs messages is set in the handlers property in the logging.properties file. This property has the following value by default:

handlers=java.util.logging.FileHandler, java.util.logging.ConsoleHandler

The default handlers are:

  • FileHandler writes formatted log records to a single file or to a set of rotating log files. By default, log files are written to logs/openidm*.log files.

  • ConsoleHandler writes formatted logs to System.err.

Additional log message handlers are listed in the logging.properties file.

Log message format

IDM supports the two default log formatters included with Java. These are set in the conf/logging.properties file:

  • java.util.logging.SimpleFormatter.format outputs a text log file that is human-readable. This is the default formatter.

  • java.util.logging.XMLFormatter outputs logs as XML, for use in logging software that can read XML logs.

IDM extends the Java SimpleFormatter with the following formatting options:

org.forgerock.openidm.logger.SanitizedThreadIdLogFormatter

This is the default formatter for console and file logging. It extends the SimpleFormatter to include the thread ID of the thread that generated each message. The thread ID helps with debugging when reviewing the logs.

In the following example log excerpt, the thread ID is [19]:

[19] May 23, 2018 10:30:26.959 AM org.forgerock.openidm.repo.opendj.impl.Activator start
INFO: Registered bootstrap repository service
[19] May 23, 2018 10:30:26.960 AM org.forgerock.openidm.repo.opendj.impl.Activator start
INFO: DS bundle started
The SanitizedThreadIdLogFormatter also encodes all control characters (such as newline characters) using URL-encoding, to protect against log forgery. Control characters in stack traces are not encoded.
org.forgerock.openidm.logger.ThreadIdLogFormatter

Similar to the SanitizedThreadIdLogFormatter, but does not encode control characters. If you do not want to encode control characters in file and console log messages, edit the file and console handlers in conf/logging.properties as follows:

java.util.logging.FileHandler.formatter = org.forgerock.openidm.logger.ThreadIdLogFormatter

java.util.logging.ConsoleHandler.formatter = org.forgerock.openidm.logger.ThreadIdLogFormatter

The SimpleFormatter (and, by extension, the SanitizedThreadIdLogFormatter and ThreadIdLogFormatter) lets you customize what information to include in log messages, and how this information is laid out. By default, log messages include the date, time (down to the millisecond), log level, source of the message, and the message sent (including exceptions). To change the defaults, adjust the value of java.util.logging.SimpleFormatter.format in your conf/logging.properties file. For more information on how to customize the log message format, refer to the related Java documentation.

Logging level

By default, IDM logs messages at the INFO level. This logging level is specified with the following global property in conf/logging.properties:

.level=INFO

You can specify different separate logging levels for individual server features which override the global logging level. Set the log level, per package to one of the following:

SEVERE (highest value)
WARNING
INFO
CONFIG
FINE
FINER
FINEST (lowest value)

For example, the following setting decreases the messages logged by the embedded PostgreSQL database:

# reduce the logging of embedded postgres since it is very verbose
ru.yandex.qatools.embed.postgresql.level = SEVERE

Set the log level to OFF to disable logging completely (Disable Logs), or to ALL to capture all possible log messages.

If you use logger functions in your JavaScript scripts, set the log level for the scripts as follows:

org.forgerock.openidm.script.javascript.JavaScript.level=level

You can override the log level settings, per script, with the following setting:

org.forgerock.openidm.script.javascript.JavaScript.script-name.level=level

For more information about using logger functions in scripts, refer to Log Functions.

It is strongly recommended that you do not log messages at the FINE or FINEST levels in a production environment. Although these levels are useful for debugging issues in a test environment, they can result in accidental exposure of sensitive data. For example, a password change patch request can expose the updated password in the Jetty logs.

Log file rotation

By default, IDM rotates log files when the size reaches 5 MB, and retains up to 5 files. All system and custom log messages are also written to these files. You can modify these limits in the following properties in the logging.properties file for your project:

# Limiting size of output file in bytes:
java.util.logging.FileHandler.limit = 5242880

# Number of output files to cycle through, by appending an
# integer to the base file name:
java.util.logging.FileHandler.count = 5

There is currently no logging.properties setting for time-based rotation of server log files. However, on UNIX systems you can use the logrotate command to schedule server log rotation at a regular interval. For more information, refer to the logrotate man page.

Disable logs

If necessary, you can disable logs. For example, to disable ConsoleHandler logging, make the following changes in your project’s conf/logging.properties file before you start IDM.

Set java.util.logging.ConsoleHandler.level = OFF, and comment out other references to ConsoleHandler, as shown in the following excerpt:

# ConsoleHandler: A simple handler for writing formatted records to System.err
#handlers=java.util.logging.FileHandler, java.util.logging.ConsoleHandler
handlers=java.util.logging.FileHandler
...
# --- ConsoleHandler ---
# Default: java.util.logging.ConsoleHandler.level = INFO
java.util.logging.ConsoleHandler.level = OFF
#java.util.logging.ConsoleHandler.formatter = ...
#java.util.logging.ConsoleHandler.filter=...