On this page:
This page 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 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.xml file or as system properties in the startup script of your JVM. See Java Agent Configuration Properties.
- Check the Agent logs directory located at
- 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:
ERROR com.singularity.JavaAgent - Could Not Start Java Agent
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
Caused by: com.singularity.ee.agent.configuration.a:
This is usually caused because of incorrect configuration in the
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 (
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
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.