Server logs

IDM uses logback to generate server logs.

Before 8.0, IDM used java.util.logging (JUL) to generate its logs. Learn more about producing logs in the older format in PatternLayoutEncoder and Configuring ConsoleAppender.

Server logging isn’t the same as the audit service. The audit service logs activity on the IDM system, such as access and synchronization. Server logging records information about the internal workings of IDM, such as system messages, error reporting, service loading, and startup and shutdown messaging.

The default location for the server logging configuration file is your project’s conf/logback.xml file. You can configure this location by setting the LOGGING_CONFIG environment variable in your project’s startup.sh file.

Changes to logging settings take effect without restarting the server. You can configure the interval at which the system scans for updates using the following tag:

<configuration scan="true" scanPeriod="30 seconds">

You can specify a global logging level:

<root level="INFO">
    <appender-ref ref="console" />
    <appender-ref ref="file" />
</root>

Log appenders

IDM logs messages using <appender> tags in the logback.xml file. The three default appenders are:

RollingFileAppender 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. Rotated files will have a date within the file name, such as openidm-2025-03-11.log.
ConsoleAppender writes formatted logs to System.out.
OpenTelemetryAppender writes formatted JSON logs to an OpenTelemetry collector using the OpenTelemetry Protocol (OTLP).

Additional log message handlers are listed in the logback.xml file.

Log appender settings

You can configure logback appender settings in the conf/logback.xml file. For example:

<appender name="OpenTelemetry" class="io.opentelemetry.instrumentation.logback.appender.v1_0.OpenTelemetryAppender">
  <captureExperimentalAttributes>true</captureExperimentalAttributes>
  <captureMdcAttributes>*</captureMdcAttributes>
</appender>

The available settings are:

Appender setting Type Default Description

captureExperimentalAttributes

Boolean

false

Enables the capture of experimental log attributes thread.name and thread.id.

captureCodeAttributes

Boolean

false

Enables the capture of source code attributes.

Capturing source code attributes at logging sites might add a performance overhead.

captureMarkerAttribute

Boolean

false

Enables the capture of Logback markers as attributes.

captureKeyValuePairAttributes

Boolean

false

Enables the capture of Logback key-value pairs as attributes.

captureLoggerContext

Boolean

false

Enables the capture of Logback logger context properties as attributes.

captureArguments

Boolean

false

Enables the capture of Logback logger arguments.

captureLogstashMarkerAttributes

Boolean

false

Enables the capture of Logstash markers, supported are those added to logs using Markers.append(), Markers.appendEntries(), Markers.appendArray(), and Markers.appendRaw() methods.

captureLogstashStructuredArguments

Boolean

false

Enables the capture of Logstash StructuredArguments as attributes, such as StructuredArguments.v() and StructuredArguments.keyValue().

captureMdcAttributes

String

Comma-separated list of Mapped Diagnostic Context (MDC) attributes to capture. Use the wildcard character * to capture all attributes.

captureEventName

Boolean

false

Enables moving the event.name attribute, which is captured by one of the other mechanisms that captures attributes, to the log event name.

numLogsCapturedBeforeOtelInstall

Integer

1000

Log telemetry is emitted after the initialization of the OpenTelemetry Logback appender with an OpenTelemetry object. This setting allows you to modify the size of the cache used to replay the first logs. The thread.id attribute isn’t captured.

Configuring `RollingFileAppender`

The rolling file appender writes formatted log records to a single file or to a set of rotating log files. To configure it, you might need to:

Update the <file> tag to contain the path to your default log file.
Set the ThresholdFilter to the minimum log level for your appender.
Enable or disable the logger.LogbackLogFilter.
Configure the <RollingPolicy>.
Specify the <encoder>.

The file appender supports the following configuration tags:

<file>

Contains the path for the default log file, for example:

<file>path/to/openidm/logs/logback.log</file>

<filter>

Filters log events. Use class="ThresholdFilter" and the <level> tag to configure the log level. This should be the minimum log level for your appender, for example:

<filter class="ThresholdFilter">
    <level>TRACE</level>
</filter>

Use class="org.forgerock.openidm.logger.LogbackLogFilter" to filter some common "noise" from the logs, for example:

<filter class="org.forgerock.openidm.logger.LogbackLogFilter" />

<rollingPolicy>: Controls the system’s behavior during log rotation. By default, this is TimeBasedRollingPolicy with a daily rolling option. SizeAndTimeBasedRollingPolicy is also supported, though you should only use it in cases where performance isn’t a concern.

Learn more about rolling policies in the logback documentation.
<encoder>: Controls the system’s log message format. By default, this is JsonEncoder, though PatternLayoutEncoder is also supported.

Learn more about encoders in the logback documentation.

Configuring `ConsoleAppender`

ConsoleAppender writes formatted logs to System.out. To configure it, you might need to:

Set the ThresholdFilter to the minimum required logging level.
Enable or disable the logger.LogbackLogFilter.
Specify the <encoder>.

The console appender has the following tags:

<filter>

Filters log events. Use class="ThresholdFilter" and the <level> tag to configure the logging level, for example:

<filter class="ThresholdFilter">
    <level>TRACE</level>
</filter>

Use class="org.forgerock.openidm.logger.LogbackLogFilter" to filter some common "noisy" entries from the logs, for example:

<filter class="org.forgerock.openidm.logger.LogbackLogFilter" />

<encoder>

Controls the system’s log message format. By default, this is JsonEncoder.

Learn more about encoders in the logback documentation.

Configuring `OpenTelemetryAppender`

OpenTelemetry (OTEL) logging is an Evolving feature in PingIDM. It’s subject to change without notice, even in a minor or maintenance release.

The OpenTelemetryAppender writes formatted JSON logs to an OTEL collector using the OTLP protocol. This appender uses the class logback.appender.v1_0.OpenTelemetryAppender.

To configure the OpenTelemetryAppender:

In the conf/logback.xml file, uncomment the following appender class and settings:

<!--
<appender name="OpenTelemetry" class="io.opentelemetry.instrumentation.logback.appender.v1_0.OpenTelemetryAppender">
    <captureExperimentalAttributes>true</captureExperimentalAttributes>
    <captureKeyValuePairAttributes>true</captureKeyValuePairAttributes>
    <captureLoggerContext>true</captureLoggerContext>
    <captureMdcAttributes>*</captureMdcAttributes>
    <numLogsCapturedBeforeOtelInstall>1000</numLogsCapturedBeforeOtelInstall>
 </appender>
-->

In the appender root tag, uncomment the "OpenTelemetry" call:

<!--
Default root logging level.
This specifies which kinds of events are logged across all loggers.
For any given facility this root level can be overridden by a facility specific level.
Note that the ConsoleHandler also has a separate level setting to limit messages printed to the console.
Loggers and Handlers may override this level.
-->

<root level="INFO">
    <appender-ref ref="console" />
    <appender-ref ref="file" />
    <appender-ref ref="OpenTelemetry" /> (1)
</root>

1	Uncomment the "OpenTelemetry" call . The appender is now available on IDM startup.

Optionally, to view more OTEL log output, change the log level to "DEBUG":
```
<root level="DEBUG">
```

Learn more about OpenTelemetry logging and Distributed tracing.

Log encoders

IDM supports two log encoders:

JsonEncoder outputs logs as a JSON object. This is the default and recommended encoder for most purposes.

Example JSON output

{
  "timestamp": 1738355903784,
  "level": "DEBUG",
  "threadName": "persisted_1738355821854_QuartzSchedulerThread",
  "loggerName": "org.forgerock.openidm.quartz.RepoJobStore",
  "context": {
    "name": "default",
    "birthdate": 1738355793181,
    "properties": {}
  },
  "mdc": {},
  "formattedMessage": "Processing 0 deferred Trigger Job Completions",
  "throwable": null
}

Learn more about JsonEncoder in the logback documentation.

PatternLayoutEncoder outputs a text log file which emulates the java.util.logging format. Enabling this option will generate logs in the same format as past versions of IDM. To enable, replace the JsonEncoder with the PatternLayoutEncoder provided in the code comments of conf/logback.xml.
Example Pattern Layout output
```
[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
```
Learn more about PatternLayoutEncoder in the logback documentation.

Log levels

Logging levels are controlled by <filter class="ThresholdFilter"> tags contained within an <appender> tag in conf/logback.xml. For example, this tag filters events with a level below DEBUG:

<filter class="ThresholdFilter">
    <level>DEBUG</level>
</filter>

The following table lists the supported threshold filter values in descending order from most to least general and includes the equivalent level in the previously supported java.util.logging:

Threshold filter concordance
Logback threshold	java.util.logging threshold
ERROR	SEVERE
WARN	WARNING
INFO	INFO
DEBUG	FINE
DEBUG	FINER
TRACE	FINEST

Set the threshold value to OFF to disable logging.

Learn more about threshold values in the logback documentation.

You can specify different logging levels for individual server features which override the global logging level. For example:

<!-- Commons api.models and OpenApiTransformer (API Descriptor) is noisy at INFO level -->
<logger name="org.forgerock.api.models" level="WARN" />
<logger name="org.forgerock.api.transform.OpenApiTransformer" level="WARN" />
<!-- Logs the output from OSGi logging -->
<logger name="org.forgerock.openidm.Framework" level="WARN" />
<!-- On restart the BarURLHandler can create warning noise -->
<logger name="org.activiti.osgi.BarURLHandler" level="ERROR" />

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

<logger name="org.forgerock.openidm.script.javascript.JavaScript" level="level" />

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

<logger name="org.forgerock.openidm.script.javascript.JavaScript.script-name" level="level" />

PingIDM

Server logs

Log appenders

Log appender settings

Configuring RollingFileAppender

Configuring ConsoleAppender

Configuring OpenTelemetryAppender

Log encoders

Log levels

Configuring `RollingFileAppender`

Configuring `ConsoleAppender`

Configuring `OpenTelemetryAppender`