This topic discusses techniques for troubleshooting agent installation and operation. In particular, it describes how to find and interpret information in agent log files.
Resolving Java Agent Startup Issues
The first thing the Java agent does upon application startup is to register with the Controller. Once registered, the agent should appear in the Settings > AppDynamics Agents list.
If you do not see the agent in the list within a few minutes, check the following:
- Make sure you have restarted the application server.
- Verify that the
javaagentargument has been added to the startup script of your JVM.
- Verify that you configured the agent-controller communication properties and agent identification properties in the
controller-info.xmlfile or as system properties in the startup script of your JVM. See Java Agent Configuration Properties.
- Check the Agent logs directory located at
<agent_home>/logs/<Node_Name>for the agent.log file.
- Verify that the Agent is compatible with the Controller. For details see Agent and Controller Compatibility.
Locating the Java Agent Log Files
Agent log files are located in the
The agent.log file is the recommended file to help you with troubleshooting. This log can indicate the following:
- Incomplete information in your Agent configuration
- The Controller port is blocked
- Incorrect file permissions
Error messages related to starting the Java Agent use this format:
Resolving Incomplete Agent Configuration Issues
The following table lists the typical error messages for incomplete Agent configuration:
Cannot connect to the Agent - ERROR com.singularity.XMLConfigManager -
This indicates that the value for the Controller port in controller-info.xml is missing. Add the Controller port and host value to resolve:
Caused by: com.singularity.ee.agent.configuration.a:
This is usually caused because of incorrect configuration in the Controller-info.xml file.
Ensure that the information for agent communication (Controller host and port) and agent identification (application, tier and node names) is correctly configured.
Alternatively, you can also use the system properties (-D options) or environment variables to configure these settings.
Unblocking the Controller Port
The following table lists the typical error message when the Controller port is blocked in your network:
ERROR com.singularity.CONFIG.ConfigurationChannel - Fatal transport error: Connection refused
Try pinging the Controller from the machine where you have configured the application agent.
To check if a port is blocked in the network, use the commands:
The default ports are:
Correcting File Permission Issues
The following table lists the typical error message when the file permissions are not correct:
ERROR com.singularity.JavaAgent - Could Not Start Java Agent com.singularity.ee.agent.appagent.kernel.spi.c: Could not start services"
This is usually caused because of incorrect permissions for log files. To troubleshoot:
Confirm whether the user who is running the server has read and write permission on the agent directories.
If the user has chmod a-r equivalent permission, change the permission to chmod a+r "<agent_home>"
Maximum Async Handoff Call Graph Samples Error
The following error indicates that the number of handoffs in an asynchronous has exceeded the limit:
This can result from transactions being misidentified as async transactions. In AppDynamics 3.6 and later, all Runnables, Callables and Threads are instrumented by default except those that are excluded by the agent configuration in
In some environments, this may result in too many classes being instrumented, or cause common classes in a framework that implements the Runnable interface to be mistaken for asynchronous activity when it is not, for example, Groovy applications using Clojure.
To debug, check the call graph for asynchronous activities that are misidentified as asynchronous activities. If found, exclude the packages that are not really asynchronous activities.