---
title: Server logs
description: IDM uses logback to generate server logs.
component: pingidm
version: 8.1
page_id: pingidm:monitoring-guide:server-logs
canonical_url: https://docs.pingidentity.com/pingidm/8.1/monitoring-guide/server-logs.html
keywords: ["Monitoring", "JSON", "Configuration", "Logs"]
section_ids:
  log-appenders: Log appenders
  log-appender-settings: Log appender settings
  logging-file-appender: Configuring RollingFileAppender
  logging-console-appender: Configuring ConsoleAppender
  logging-opentelemetry-appender: Configuring OpenTelemetryAppender
  log-message-format: Log encoders
  log-levels: Log levels
---

# Server logs

IDM uses [logback](https://logback.qos.ch/manual/introduction.html) 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](#pattern-layout-encoder) and [Configuring `ConsoleAppender`](#logging-console-appender). |

Server logging isn't the same as [the audit service](../audit-guide/audit.html). 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:

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

You can specify a global [logging level](#log-levels):

```xml
<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`](#logging-file-appender) 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`](#logging-console-appender) writes formatted logs to `System.out`.

* [`OpenTelemetryAppender`](#logging-opentelemetry-appender) writes formatted JSON logs to an [OpenTelemetry collector](https://opentelemetry.io/docs/collector/) using the [OpenTelemetry Protocol (OTLP)](https://github.com/open-telemetry/opentelemetry-proto/tree/main/docs).

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:

```xml
<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.  &#xA;&#xA;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:

1. Update the `<file>` tag to contain the path to your default log file.

2. Set the `ThresholdFilter` to the minimum log level for your appender.

3. Enable or disable the `logger.LogbackLogFilter`.

4. Configure the `<RollingPolicy>`.

5. Specify the `<encoder>`.

The file appender supports the following configuration tags:

* \<file>

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

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

* \<filter>

  Filters log events. Use `class="ThresholdFilter"` and the `<level>` tag to configure the [log level](#log-levels). This should be the minimum log level for your appender, for example:

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

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

  ```xml
  <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](https://logback.qos.ch/manual/appenders.html#RollingFileAppender).

- \<encoder>

  Controls the system's [log message format](#log-message-format). By default, this is `JsonEncoder`, though `PatternLayoutEncoder` is also supported.

  Learn more about encoders in the [logback documentation](https://logback.qos.ch/manual/encoders.html).

### Configuring `ConsoleAppender`

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

1. Set the `ThresholdFilter` to the minimum required logging level.

2. Enable or disable the `logger.LogbackLogFilter`.

3. 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:

  ```xml
  <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:

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

* \<encoder>

  Controls the system's [log message format](#log-message-format). By default, this is `JsonEncoder`.

  Learn more about encoders in the [logback documentation](https://logback.qos.ch/manual/encoders.html).

### Configuring `OpenTelemetryAppender`

|   |                                                                                                                                                                                                                                                              |
| - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|   | [OpenTelemetry (OTEL)](https://opentelemetry.io/docs/what-is-opentelemetry/) logging is an [Evolving](../release-notes/appendix-interface-stability.html) 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`:

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

   ```xml
   <!--
   <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>
   -->
   ```

2. In the appender `root` tag, uncomment the `"OpenTelemetry"` call:

   ```xml
   <!--
   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. |

3. Optionally, to view more OTEL log output, change the [log level](#log-levels) to `"DEBUG"`:

   ```xml
   <root level="DEBUG">
   ```

Learn more about [OpenTelemetry logging](opentelemetry-logging.html) and [Distributed tracing](distributed-tracing.html).

## 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

  ```json
  {
    "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](https://logback.qos.ch/manual/encoders.html#JsonEncoder).

- `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](https://logback.qos.ch/manual/encoders.html#PatternLayoutEncoder).

## 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:

```xml
<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](https://logback.qos.ch/manual/architecture.html#basic_selection).

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

```xml
<!-- 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:

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

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

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