--- title: Managing PingGateway logs description: "Configure PingGateway logging: set log levels, customize Logback, capture route messages, and log script events" component: pinggateway version: 2026 page_id: pinggateway:maintenance-guide:logging canonical_url: https://docs.pingidentity.com/pinggateway/2026/maintenance-guide/logging.html revdate: 2026-02-23T12:00:00Z keywords: ["Maintenance", "Configuration", "Logs", "Objects", "Scripts", "URI"] section_ids: logging-default-behavior: Default logging behavior logging-changing-all: Using a custom Logback file logging-level-set-global: Change the global log level logging-level-objects: Change the log level for different object types logging-format: Change the character set and format of log messages logging-scripts: Log in scripts logging-baseuri: Log the BaseUriDecorator logging-exception: Stop exception logging logging-propagation: Reduce logging when propagating disconnections logging-capture: Capture the context or entity of messages for routes logging-duplicate-messages: Limit repetitive log messages --- # Managing PingGateway logs Log messages in PingGateway and third-party dependencies are recorded using the Logback implementation of the Simple Logging Facade for Java (SLF4J) API. The following log levels are supported: * `TRACE` * `DEBUG` * `INFO` * `WARN` * `ERROR` * `ALL` * `OFF` You can find a full description of the options for logging in [the Logback website](https://logback.qos.ch). ## Default logging behavior | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | By default, when you change the Logback configuration, you must restart PingGateway to load the changes.You can avoid restarting PingGateway more than once by explicitly configuring Logback to rescan its configuration periodically. (You must still restart PingGateway once after you update the default configuration for the first time.)Use this for PingGateway in [development mode](../configure/operating-modes.html#development-mode) and in production mode on systems that start slowly, where a restart could cause a potential service interruption. This isn't useful for PingGateway in production mode on infrastructure like Docker or Kubernetes where the configuration files you deploy are immutable.To let Logback scan for changes, create a custom `logback.xml` file in `$HOME/.openig/config/logback.xml`, and make sure the `` element has `scan` and `scanPeriod` attributes. This example tells Logback to rescan its configuration every five seconds:```none ```Learn more in [Using a custom Logback file](#logging-changing-all). | By default, log messages are recorded with the following configuration: * When PingGateway starts, it writes log messages for PingGateway and third-party dependencies on the console and in the `$HOME/.openig/logs/route-system.log` file, where `$HOME/.openig` is the instance directory. * When a capture point for the default CaptureDecorator is defined in a route, for example, when `"capture: "all"` is set as a top-level attribute of the JSON, log messages for requests and responses passing through the route are written to a log file in `$HOME/.openig/logs`. When no capture point is defined in a route, only exceptions thrown during request or response processing are logged. Learn more in [Capturing log messages for routes](#logging-capture) and [CaptureDecorator](../reference/CaptureDecorator.html). * By default, log messages with the level `INFO` or higher are recorded, with the titles and the top line of the stack trace. Messages on the console are highlighted with a color related to their log level. The content and format of logs in PingGateway is defined by the reference `logback.xml` delivered with PingGateway. This file defines the following configuration items for logs: * A root logger to set the overall log level, and to write all log messages to the `SIFT` and `STDOUT` appenders. * A `STDOUT` appender to define the format of log messages on the console. * A `SIFT` appender to separate log messages according to the key `routeId`, to define when log files are rolled, and to define the format of log messages in the file. * An exception logger, called `LogAttachedExceptionFilter`, to write log messages for exceptions attached to responses. ```xml true %nopex[%thread] %highlight(%-5level) %boldWhite(%logger{35}) @%mdc{routeId:-system} - %replace(%message){'([\r\n])(.)', '$1[CONTINUED]$2'}%n%highlight(%replace(%rootException{short}){'(^|[\r\n])(.)', '$1[CONTINUED]$2'}) routeId system ${instance.dir}/logs/route-${routeId}.log ${instance.dir}/logs/route-${routeId}-%d{yyyy-MM-dd}.%i.log 100MB 30 3GB %nopex%date{"yyyy-MM-dd'T'HH:mm:ss,SSSXXX", UTC} | %-5level | %thread | %logger{20} | @%mdc{routeId:-system} | %replace(%message%n%xException){'([\r\n])(.)', '$1[CONTINUED]$2'} ``` Source: [logback.xml](../_attachments/config/logback.xml) Learn about logging to an OpenTelemetry endpoint in [Log to an OpenTelemetry service](monitoring.html#monitoring-otlp-logging). ## Using a custom Logback file To change the logging behavior, create a new logback file at `$HOME/.openig/config/logback.xml`, and restart PingGateway. The custom Logback file overrides the default configuration. To take into account edits to `logback.xml`, stop and restart PingGateway, or edit the `configuration` parameter to add a scan and an interval: ```none ``` The `logback.xml` file is scanned after both of the following criteria are met: * The specified number of logging operations have occurred, where the default is 16. * The `scanPeriod` has elapsed. If the custom `logback.xml` contains errors, messages like these are displayed on the console but log messages aren't recorded: ``` 14:38:59,667 |-ERROR in ch.qos.logback.core.joran.spi.Interpreter@20:72 …​ 14:38:59,690 |-ERROR in ch.qos.logback.core.joran.action.AppenderRefAction …​ ``` ## Change the global log level The global log level is set by default to `INFO` by the following line of the default `logback.xml`: ```xml ``` The log level set in `logback.xml` supercedes the log level set by environment variables. When the global log level is not set in `logback.xml`, set the global log level. * To persist the log level for all future PingGateway instances: * Add an environment variable in `$HOME/.openig/bin/env.sh`, where `$HOME/.openig` is the instance directory: ```shell export ROOT_LOG_LEVEL=DEBUG ``` * Alternatively, add a system property in `$HOME/.openig/bin/env.sh`, where `$HOME/.openig` is the instance directory: ```shell export JAVA_OPTS="-DROOT_LOG_LEVEL=DEBUG" ``` If both an environment variable and system property is set, the system property takes precedence. * To persist the log level for PingGateway instances launched from the same shell, add an environment variable in the shell before you start PingGateway: * Linux * Windows ```console $ export ROOT_LOG_LEVEL=DEBUG $ /path/to/ping-gateway-2026.3.0/bin/start.sh $HOME/.openig ``` ``` C:\set ROOT_LOG_LEVEL=DEBUG C:\path\to\ping-gateway-2026.3.0\bin\start.bat %appdata%\OpenIG ``` * To persist the log level for a single PingGateway instance: * Linux * Windows ```console $ export ROOT_LOG_LEVEL=DEBUG /path/to/ping-gateway-2026.3.0/bin/start.sh $HOME/.openig ``` ```windows C:\set ROOT_LOG_LEVEL=DEBUG C:\path\to\ping-gateway-2026.3.0\bin\start.bat %appdata%\OpenIG ``` ## Change the log level for different object types To change the log level for a single object type without changing it for the rest of the configuration, edit `logback.xml` to add a logger defined by the fully qualified class name or package name of the object and set its log level. The following line in `logback.xml` sets the ClientHandler log level to `ERROR`, but doesn't change the log level of other classes or packages: ```xml ``` To facilitate debugging, in `logback.xml` add loggers defined by the fully qualified package name or class name of the object. For example, add loggers for the following feature: | Feature | Logger | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | OAuth 2.0 client authentication:- [AuthorizationCodeOAuth2ClientFilter](../reference/AuthorizationCodeOAuth2ClientFilter.html) - [ClientCredentialsOAuth2ClientFilter](../reference/ClientCredentialsOAuth2ClientFilter.html) - [ResourceOwnerOAuth2ClientFilter](../reference/ResourceOwnerOAuth2ClientFilter.html) | `org.forgerock.secrets.oauth2` | | Expression resolution | `org.forgerock.openig.el``org.forgerock.openig.resolver` | | WebSocket notifications | `org.forgerock.openig.tools.notifications.ws` | | JWT-based session management | `org.forgerock.openig.jwt` | | OAuth 2.0 and OpenID Connect and token resolution and validation | `org.forgerock.openig.filter.oauth2` | | AM policies, SSO, CDSSO, and user profiles | `org.forgerock.openig.openam``org.forgerock.openig.tools` | | SAML | `org.forgerock.openig.handler.saml` | | UMA | `org.forgerock.openig.uma` | | WebSocket tunnelling | `org.forgerock.openig.websocket` | | Secret resolution | `org.forgerock.secrets.jwkset``org.forgerock.secrets.keystore``org.forgerock.secrets.oauth2``org.forgerock.secrets.propertyresolver``org.forgerock.openig.secrets.Base64EncodedSecretStore` | | AllowOnlyFilter | `org.forgerock.openig.filter.allow.AllowOnlyFilter.` | | Condition of a route | `org.forgerock.openig.handler.router.RouterHandler` | | Header field size | `io.vertx.core.http.impl.HttpServerImpl` | ## Change the character set and format of log messages By default, logs use the system default character set where PingGateway is running. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | | If your logs might contain characters that aren't in your system character set, edit `logback.xml` to change the `encoder` part of the SIFT appender. | The following lines add the date to log messages and change the character set: ```xml %d{yyyyMMdd-HH:mm:ss} | %-5level | %thread | %logger{20} | %message%n%xException UTF-8 ``` Learn more about what information you can include in the logs and its format in [PatternLayoutEncoder](https://logback.qos.ch/manual/encoders.html#PatternLayoutEncoder) and [Layouts](https://logback.qos.ch/manual/layouts.html) in the Logback documentation. ## Log in scripts The [logger](https://www.slf4j.org/api/org/slf4j/Logger.html) object provides access to a unique SLF4J logger instance for scripts. Events are logged as defined in by a dedicated logger in `logback.xml` and are included in the logs with the name of with the scriptable object. To log events for scripts: * Add logger objects to the script to enable logging at different levels. For example, add some of the following logger objects: ```groovy logger.error("ERROR") logger.warn("WARN") logger.info("INFO") logger.debug("DEBUG") logger.trace("TRACE") ``` * Add a logger to `logback.xml` to reference the scriptable object and set the log level. The logger is defined by the type and name of the scriptable object that references the script, as follows: * ScriptableFilter: `org.forgerock.openig.filter.ScriptableFilter.filter_name` * ScriptableHandler: `org.forgerock.openig.handler.ScriptableHandler.handler_name` * ScriptableThrottlingPolicy: `org.forgerock.openig.filter.throttling.ScriptableThrottlingPolicy.throttling_policy_name` * ScriptableAccessTokenResolver: `org.forgerock.openig.filter.oauth2.ScriptableAccessTokenResolver.access_token_resolver_name` For example, the following logger logs trace-level messages for a ScriptableFilter named `cors_filter`: ```xml ``` The resulting messages in the logs contain the name of the scriptable object: ```none 14:54:38:307 | TRACE | http-nio-8080-exec-6 | o.f.o.f.S.cors_filter | TRACE ``` ## Log the BaseUriDecorator During setup and configuration, it can be helpful to display log messages from the BaseUriDecorator. To record a log message each time a request URI is rebased, edit `logback.xml` to add a logger defined by the fully qualified class name of the BaseUriDecorator appended by the name of the baseURI decorator: ```xml ``` Each time it rebases a request URI, PingGateway logs a message similar to the following: ```none ... o.f.o.d.b.B.b.{Router}/handler| Rebasing request to https://app.example.com:8444 ``` ## Stop exception logging To stop recording log messages for exceptions, edit `logback.xml` to set the level to `OFF`: ```xml ``` ## Reduce logging when propagating disconnections When using HTTP/2 and propagating disconnections from the user-agent to the protected application, edit `logback.xml` to change the log level for the `DefaultHttp2ConnectionDecoder` to `WARN`: ```xml ``` At the level of `INFO`, the logging for this component is noisy when PingGateway propagates disconnections. ## Capture the context or entity of messages for routes To capture the context or entity of inbound and outbound messages for a route or for an individual handler or filter in the route, configure a CaptureDecorator. Captured information is written to SLF4J logs. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | When debugging, use a `CaptureDecorator` to capture and log details of requests and responses.Be aware increased logging consumes resources, such as disk space, and can cause performance issues.In production deployments, avoid setting `"captureEntity": true`. This causes PingGateway to log the entire body, including sensitive data. Usually, `"captureContext": true` logs sufficient information to debug problems. If it isn't needed, reduce logging further by setting `"captureContext": false`. | You can find more information about the decorator configuration in [CaptureDecorator](../reference/CaptureDecorator.html). Studio provides an easy way to capture messages while developing your configuration. The following image illustrates the capture points where you can log messages on a route: ![Capture points for requests and responses passing through a route](_images/ig-ping-identity-platform-capture.png)Figure 1. Capturing log messages for routesCapture messages on a route in Studio 1. In Studio, select [icon: sitemap, set=fa]ROUTES, and then select a route with the [icon: list-ul, set=fa]icon. 2. On the left side of the screen, select [icon: search, set=fa]Capture, and then select capture options. You can capture the body and context of messages passing to and from the user agent, the protected application, and the Ping Identity Platform. 3. Select [icon: cloud-upload-alt, set=fa]Deploy to push the route to the PingGateway configuration. You can check the `$HOME/.openig/config/routes` folder to see that the route is there. 4. Access the route, and then check `$HOME/.openig/logs` for a log file named by the route, where `$HOME/.openig` is the instance directory. The log file should contain the messages defined by your capture configuration. ### Limit repetitive log messages To keep log files clean and readable, and to prevent log flow attacks, limit the number of repeat log messages. Add a custom `logback.xml` with a `DuplicateMessageFilter`. This filter detects duplicate messages, and after the specified number of repetitions, drops repeated messages. The following example allows five repetitions of a log message and holds the last 10 repeated messages in the cache: ```xml ``` The DuplicateMessageFilter has the following limitations: * Filters out **all** duplicate messages. It doesn't filter per logger, or logger instance, or logger name. * Detects repetition of raw messages, meaning that the following example messages are considered as repetition: ```groovy logger.debug("Hello {}.", name0); logger.debug("Hello {}.", name1); ``` * Doesn't limit the lifespan of the cache. After the specified number of repetitions is reached, the repeated log messages never appear again, even if they're frequently hit.