Configure 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.

Server logging is configured 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.

The way in which messages are logged 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

Two handlers are listed by default:

  • 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.

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 formatter is used by default.

  • 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, change 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, see the related Java documentation.

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 (see in 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

For more information about using logger functions in scripts, see "Log Functions".

Important

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 files are rotated when the size reaches 5 MB, and IDM 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

Note

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, see the logrotate man page.

If required, you can also 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=...
Read a different version of :