How To

How do I collect debug logs in OpenIG 4.x for troubleshooting?

Last updated Jan 5, 2021

The purpose of this article is to provide information on collecting debug logs in OpenIG for troubleshooting. This includes collecting message level SAML logs if you are using OpenIG for SAML federation.

3 readers recommend this article

This article has been archived and is no longer maintained by ForgeRock.


Logging in IG 5 has changed and is now solely based on a Logback implementation of the Simple Logging Facade for Java® (SLF4J) API. Configurations will require updating if they are based on earlier versions of the product, see IG 5 Release Notes › Important Changes to Existing Functionality for an overview of the logging and other key changes. 

See How do I generate more detailed debug logs to diagnose an issue in IG (All versions)? for further information about collecting debug logs and other useful logs in IG 5 and later.

This article covers collecting the following debug logs:

Collecting OpenIG 4.x logs

There are two log outputs you should collect for troubleshooting OpenIG: Entity and Context logs. The output from these logs is sent to one of the following depending on your logging configuration:

  • stdout (catalina.out if you are using Apache Tomcat™) - ConsoleLogSink. This is the default logging mechanism.
  • log file - FileLogSink.

OpenIG 4.5 introduced a new option (Slf4jLogSink) to allow you to access all log messages from SLF4J loggers using the Logback implementation of the SLF4J API. See OpenIG 4.5 Gateway Guide › Logging Events in OpenIG and OpenIG 4.5 Configuration Reference › Slf4jLogSink — delegate log writing to SLF4J for further information. This has been replaced in IG 5 with the SLF4J class Logger. See IG 5 Release Notes › Important Changes to Existing Functionality for further information.

You can enable OpenIG to capture these log files as follows:

  1. Update the config.json file (located in the $HOME/.openig/config/ directory) and set the captureEntity and captureContext properties to true for the default CaptureDecorator: { "name": "capture", "type": "CaptureDecorator", "config": { "captureEntity": true, "captureContext": true } }
  2. Update the config.json file and set the level to DEBUG for the default ConsoleLogSink or FileLogSink depending on which one you are using:
    • ConsoleLogSink: { "name": "LogSink", "type": "ConsoleLogSink", "config": { "level": "DEBUG" } }
    • FileLogSink: { "name": "LogSink", "type": "FileLogSink", "config": { "file": "/tmp/gateway.log", "level": "DEBUG" } }
  3. Restart OpenIG to apply these changes. The log details are output to stdout or the file you specified. 

Example log output

The following example log shows the type of information you will see in the stdout if the logs have been correctly generated:

INFO: Server startup in 5194 ms ... ------------------------------ THU JUL 07 11:21:02 EST 2016 (DEBUG) {Router}/handler Added route '05-federate.json' defined in file '/home/suser/.openig/config/routes/05-federate.json' ... --- (request) exchange:641186666 ---> GET ...

Once you have reproduced the problem and captured the log output, you may want to revert the captureEntity and captureContext properties to false again and revert the log level to INFO to avoid filling up disk space.

Collecting SAML logs

You can enable OpenIG to capture the SAML log file (libSAML2) at message level as follows:

  1. Update the file (located in the $HOME/.openig/SAML directory) and set these two properties as follows:$HOME/.openig/SAML/debug
  2. Restart OpenIG to apply these changes. The libSAML2 log file is output to the debug directory you specified.

Once you have reproduced the problem and captured the libSAML2 log file, you may want to revert the property to error again to avoid filling up the disks where the debug logs are stored. 

See Also

Gateway Guide › Logging Events in OpenIG

Related Training


Related Issue Tracker IDs


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.