How do I enable debug logging for troubleshooting Agents (All versions)?
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 |
|
-- | 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:
- 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:
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=debugThis 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:
com.iplanet.services.debug.level=messageThis 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
$ ./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)?
Agent Debug Level (Web)
Agent Debug Level (Java)
Related Training
ForgeRock Access Management Deep Dive (AM-410)
Related Issue Tracker IDs
N/A