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

Background information

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

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:

• Startup issues and local configurations: set the log levels in the agent.conf file (located in the /path/to/web_agents/agent_version/instances/Agent_nnn/config directory).
• Centralized configurations - once the agent is up and running: set the log levels using the AM admin UI, Amster or ssoadm:.

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

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

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:

• Startup issues and local configurations: set the log levels in the properties file (located in the /config directory where the Java agent is installed).
• Centralized configurations - once the agent is up and running: set the log levels using the AM admin UI, Amster or ssoadm.

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:

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:

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