How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I enable debug logging for troubleshooting Agents (All versions)?

Last updated Mar 30, 2023

The purpose of this article is to provide information on raising the debug logging level for Web and Java Agents. Support frequently use these logging levels for troubleshooting Agent issues but they are not generally recommended for production due to an increase in log size.


3 readers recommend this article

Background information

There are different debug levels available to Agents (varying according to type):

Level Description Available to Web Agents? Available to Java Agents?
Off Disables debug logging. -- Yes
Error Logs only error messages. Yes (default) Yes (default)
Warning Logs both warning and error messages. Yes Yes
Info Logs info, warnings and errors messages. Yes --
Message Logs debug, info, warning and error messages. Yes Yes
All Logs detailed diagnostic messages and debugging information. Yes --
Trace

Extremely verbose logging that should only be used if other debug levels have failed to reveal the problem. This debug level will quickly fill up disk space and can impact performance too.

Trace is the highest level of logging in Java Agents 5.10 and later.

-- Yes
On
  • Java Agents 5.10 and later: Trace level logs are written to file (instead of standard output)
  • Pre-Java Agents 5.10: Highest level of logging that is written to the standard output, as opposed to file.
-- Yes

By default, the Agent debug log is named and located as follows:

  • Web Agents - debug.log, which is located in the /path/to/policy_agent/instances/agent_n/logs/debug directory.
  • Java Agents - debug.out, which is located in the /path/to/policy_agent/agent_n/logs/debug directory.

Web Agents

Depending on what you are trying to troubleshoot for web agents, and whether you have a local or centralized configuration will affect where you need to set the log levels:

The log levels in AM correspond to log levels in the agent.conf file as follows:

AM (admin UI, ssoadm and Amster) log levels agent.conf file log levels
Error error
Warning warning
Info info
Message warning
All debug

Once you have reproduced the problem and captured the debug.log, you should revert to the Error debug level to avoid filling up the disk where the debug log is stored.

Troubleshooting startup issues and local configurations

To troubleshoot startup issues and local configurations once they are up and running, you should set the log level in the agent.conf file. Edit the com.sun.identity.agents.config.debug.level property and set it as follows (you must use lowercase):

com.sun.identity.agents.config.debug.level=debug

This local level setting will be overwritten once the agent has fully started up but is useful for troubleshooting startup issues.

Troubleshooting issues once the agent is up and running (centralized configurations)

To troubleshoot centralized configurations once the agent is up and running, you should set the log level using either the AM admin UI, Amster or ssoadm. These examples show the log level being raised to All:

  • AM admin UI: navigate to: Realms > [Realm Name] > Applications > Agents > Web > [Agent Name] > Global > Agent Debug Level and select All.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster? with these values:
    • Entity: WebAgents
    • Property: agentDebugLevel
    • Value: All
  • ssoadm: enter the following command: $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.debug.level=allreplacing [realmname], [agentname], [adminID] and [passwordfile] with appropriate values.

Java Agents

Depending on what you are trying to troubleshoot for Java agents, and whether you have a local or centralized configuration will affect where you need to set the log levels:

Once you have reproduced the problem and captured the debug.out file, you should revert to the Error debug level to avoid filling up the disk where the debug log is stored.

Troubleshooting startup issues and local configurations

To troubleshoot startup issues and local configurations once they are up and running, you should set the log level in the AgentBootstrap.properties file (Java Agents 5.8 and later) or the OpenSSOAgentBootstrap.properties file (pre-5.8). Edit the com.iplanet.services.debug.level property and set the required debug level, for example:

com.iplanet.services.debug.level=message

This local level setting will be overwritten once the agent has fully started up but is useful for troubleshooting startup issues. Startup issues are written to the web application container log (for example, catalina.out for Apache Tomcat™) not the debug.out file.

Troubleshooting issues once the agent is up and running (centralized configurations)

For centralized configurations, you can enable Message level debugging for Java agents using either the AM admin UI, Amster or ssoadm:

  • AM admin UI: navigate to: Realms > [Realm Name] > Applications > Agents > Java > [Agent ID] > Global > Agent Debug Level and select message.
  • Amster: follow the steps in How do I update property values in AM (All versions) using Amster? with these values:
    • Entity: J2eeAgents
    • Property: debugLevel
    • Value: message
  • ssoadm: enter the following command: $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.iplanet.services.debug.level=messagereplacing [realmname], [agentname], [adminID] and [passwordfile] with appropriate values.

Trace debug logging

Trace debug logging is an advanced custom option. It can be set in the admin UI in AM 7 and later by navigating to Realms > [Realm Name] > Applications > Agents > Java > [Agent Name] > Advanced > Custom Properties and adding the following property:

com.iplanet.services.debug.level=trace

In AM 6.x, you must use ssoadm to set this property instead using the following command:

$ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.freeformproperties=com.iplanet.services.debug.level=trace

See Also

How do I collect all the data required for troubleshooting AM and Agents (All versions)?

Troubleshooting AM and Agents

Agents and policies in AM

Agent Debug Level (Web)

Agent Debug Level (Java)

Related Training

ForgeRock Access Management Deep Dive (AM-410)

Related Issue Tracker IDs

N/A


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