To begin monitoring a Java application using AppDynamics, you install the AppDynamics Java Agent into the application JVM:
Prepare to Install the Java Agent
Consider the following as you decide where and how to deploy the AppDynamics Java Agent:
Instrument a Custom Java Runtime Image
You can use the Java Agent to instrument an application running on a custom Java runtime image constructed with J-link. To instrument the agent, the custom runtime requires the following modules:
The Java Agent typically adds between 0% to 2% additional CPU consumption.
However, certain factors can increase CPU overhead from the agent beyond 2%. These include the use of resource-intensive AppDynamics features, such as asynchronous transaction tracking. Very active environments or configuration settings that result in a high number of metrics or snapshots reported per minute can also affect agent resource consumption.
In all cases, AppDynamics recommends that you test the agent in a staging environment, and monitor resource consumption of your application to ensure that it remains within proper operating parameters.
If your application operates within a small margin of its existing memory resource allocation, you may choose to increase the allocation for the application. AppDynamics recommends allocating the following amounts of additional Heap and PermGen space to accommodate the agent:
For network bandwidth consumption, see Install App Server Agents.
Download and Unzip the Java Agent Distribution
You can get the agent from the Agent Download Wizard. If you have never installed an agent before, the wizard is a good place to start. The wizard populates the configuration file in the agent you download with Controller connection settings and identifying settings for the agent. After you download the agent, you can install it in the JVM.
Alternatively, you can download the agent manually, as follows:
For information on the contents of the Java Agent home directory, see Java Agent Directory Structure.
Configure the Java Agent
If you downloaded the agent from the Agent Download Wizard in the Controller, you can jump ahead to the next section, as the agent is already configured.
To configure the settings manually (or verify the wizard settings):
The following shows a controller-info.xml file with sample configuration values:
On Windows, include the drive letter in the path to the agent:
javaagent to the startup script requires a restart of the JVM. If it's not possible to restart the JVM when you are installing the agent and modifying the JVM start up script, you can attach the agent dynamically to the running Java process, as described next.
See Agent Installation by Java Framework for more information on how to install Java Agent by Java framework or technology.
Attaching the Java Agent to a Running JVM Process
Attaching the agent to a running JVM allows you to install the Java Agent without requiring a JVM restart. This approach would normally be used alongside adding the
‑javaagent argument to the JVM startup script, or some other persistent approach to ensure that the agent is loaded again at the next JVM restart. However, dynamic attachment allows you to install the agent when restarting the JVM is not possible or convenient.
Dynamic agent attachment works if:
- The JVM is version 1.6 or later.
- The JVM is an Oracle (HotSpot) JVMs (unavailable for IBM or JRockit JVMs).
Other considerations include:
- Do not attach the agent dynamically to an environment that is already instrumented (either by the AppDynamics Java Agent or another type of agent). Doing so can cause unforeseeable issues and errors.
- Attaching the AppDynamics Java Agent to a running environment will impact the performance of the application while the agent performs the class retransformation needed to instrument the application. The agent overhead will return to its normal operating level when it finishes the process, but it is important to consider the potential performance impact to production services.
To attach the agent to the JVM, follow these steps:
Determine the PID of the JVM to which you want to attach. For example, on Linux, use:
ps -A | grep java
On Windows, use:
Run the following command, replacing the placeholders for the path to the
tools.jarfile in your JDK, path to the AppDynamics Java Agent home directory, and the JVM process ID with values appropriate for your environment:
java -Xbootclasspath/a:<path_to_jdk>/lib/tools.jar -jar /<agent_home>/javaagent.jar <jvm_process_id> appdynamics.controller.hostName=<controller_hostname>,appdynamics.controller.port=<controller_port_no>,appdynamics.controller.ssl.enabled=false,appdynamics.agent.applicationName=<app_name>,appdynamics.agent.tierName=<agent_tier_name>,appdynamics.agent.nodeName=<agent_node_name>
Use the equivalent paths for Windows, including drive letter. The following shows an example with system output included:
[appduser@my_centos6 ~]$ ps -A | grep java 6780 pts/1 00:00:04 java [appduser@my_centos6 ~]$ java -Xbootclasspath/a:/usr/java/jdk1.7.0_79/lib/tools.jar -jar /home/appduser/appagent/javaagent.jar 6780 Attaching to VM  agent path >>>/home/appduser/appagent/javaagent.jar
Verify Java Agent Installation
After an installation, the agent log in
<agent_home>/logs will contain the following message:
Started AppDynamics Java Agent Successfully
If the agent log file is not present, the Java Agent may not be accessing the
javaagent command properties. To troubleshoot, check the application server log file where
STDOUT is logged. It will have the fallback log messages, useful for troubleshooting the agent.
Also, verify that the agent is able to connect to the Controller in the Controller UI. To verify, log in to the Controller UI and click the Settings cog icon at the top right of the screen, and then AppDynamics Agents. In the list, look for the agent in the list by machine hostname.