This page applies to an earlier version of the AppDynamics App IQ Platform.
For documentation on the latest version, see the 4.4 Documentation.

Skip to end of metadata
Go to start of metadata

On this page:

Related pages:

Installing the AppDynamics Java Agent requires putting the agent software on the application machine, configuring the agent settings, and adding the Java Agent to the JVM. You add the agent to the JVM by including it as a argument in the startup script for the JVM. 

To avoid permission issues, you should install the agent as the same user that owns the JVM or as an administrator on the host machine. In any case, the user that runs the JVM must have write privileges to the conf and logs directories in the Java Agent home.

While it's possible for the Java Agent to run on the same JVM as other Byte Code Injection (BCI) agents as long as the other agents do not interfere with the Java Agent class transformation, AppDynamics advises against it. As always, you should thoroughly test your deployment in a staging environment to detect possible conflicts. 

Planning for Java Agent Installation

Before installing the Java Agent, be prepared with the following information.

Planning Item


Where is the startup script for the JVM?

If using a Java service wrapper, you need to know the location of the wrapper configuration.

This is where you can add startup arguments in the script file and system properties, if needed.

What host and port is the Controller running on?

For SaaS customers, AppDynamics provides this information to you. For on-premise Controllers, this information is configured during Controller installation. See (Install the Controller or Configure Windows for Controller Hosting).

To what AppDynamic business application does this JVM belong?

Usually, all JVMs in your distributed application infrastructure belong to the same AppDynamics business application. You assign a name to the business application. For details see AppDynamics Concepts.

To what AppDynamics tier does this JVM belong?

You assign a name to the tier. For details see AppDynamics Concepts.


In addition to the JVM startup script file, two other files are important during installation:

  • javaagent.jar is the agent binary file. The -javaagent argument should specify the fully-qualified path to this file. No separate classpath arguments need to be added.
  • controller-info.xml under <agent_home>/ver<ver_number>/conf is where you add the configuration mentioned in the planning list. This file contains configuration settings specific to the agent version you are using, and take precedence over the same file in the <agent_home>/conf directory. For most settings you should use this version-specific file. 

The following sections take you through the steps for downloading and installing the Java Agent manually. Alternatively, configure the agent using Agent Download Wizard, as described in Instrument Java Applications.

Java Agent Resource Overhead

While relatively lightweight, the Java Agent does add a certain amount of overhead to the overall resource consumption of an application. The existing resource allocation for most applications can absorb the additional overhead imposed by the agent, so you do not normally need to increase the resource allocation for the application when installing the agent

However, the exact CPU or memory overhead added by the agent can vary depending upon your application and how you have configured AppDynamics.

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:

  • Maximum heap size (-Xmx): 100 MB in addition to the amount required by the application
  • Maximum PermGen (permanent generation) heap size (-XX:MaxPermSize): 20 MB in addition to the amount required by the application 

In terms of CPU consumption, the agent can add between 0% to 2% additional overhead on CPU usage. 

Certain resource-intensive AppDynamics features, such as asynchronous transaction tracking, can increase resource consumption as well. AppDynamics recommends that you monitor the memory consumption of your application to ensure that there are sufficient resources allocated to it.  

Download and Unzip the Java Agent

  1. Download the Java Agent ZIP file from AppDynamics Download Center.
  2. Extract the ZIP file to the destination directory as the same user or administrator of the JVM. Take note of the following:
    • Extract the Java Agent to a directory that is outside of your container
    • All files should be readable by the Java Agent
    • Runtime directory should be writable by the Java Agent

Note: Be sure to avoid installing the agent into a directory used by the application server, such as to the Tomcat webapps directory. To avoid this possibility, install the Java Agent to a directory outside of application server home directory, such as to \usr\local\agentsetup\appserveragent.

Agent Configuration Options and Precedence

You can configure the Java app agent settings, such as its Controller connection settings, using one of several mechanisms. Those mechanisms and the order of priority (in the case of conflicting settings) are: 

  1. Environment variable 
  2. System property 
  3. <agent_home>/ver<version_number/conf/controller-info.xml 
  4. <agent_home>/conf/controller-info.xml 

When reading its configuration, the agent checks each of these sources in the order shown and uses the value from the first source that contains a non-empty value for a particular setting.

If you used the download Wizard in the UI to get the agent, you can find the settings in the version specific controller-info.xml file. 

Configure the Java Agent Connection to the Controller

Configure properties for the Controller host name and its port number.

Configure in

Configure using System Properties










For On-premise Controller installations: By default, port 8090 is used for HTTP and 8181 is used for HTTPS communication.
For SaaS Controller service: By default, port 80 is used for HTTP and 443 is used for HTTPS communication.

Optional settings for Java Agent-to-Controller communication

Configure Java Agent Account Information (Multi-tenant mode or SaaS Installations Only) 

  • This step is required only when the AppDynamics Controller is configured in Controller Tenant Mode or when you use a SaaS Controller.
    (info) Skip this step if you are using single-tenant mode, which is the default in an on-premise installation.
  • Specify the properties for Account Name and Account Key. This information is provided in the Welcome email from the AppDynamics Support Team. You can also find this information in the <controller_install>/initial_account_access_info.txt file.

Configure using

Configure using
System Properties





Required only if your Controller is configured for multi-tenant mode or
your controller is hosted.




Required only if your Controller is configured for multi-tenant mode or
your controller is hosted.


Configure the Business Application, Tier, and Node

When configuring a Java Agent, you identify the business application, tier, and node it belongs to in the AppDynamics application model. See
AppDynamics Concepts and Name Business Applications, Tiers, and Nodes for more information on this model.

You can configure these properties using either the controller-info.xml file or JVM startup script options. Use these guidelines when configuring agents:

  • Configure items that are common for all the nodes in the controller-info.xml file.
  • Configure information that is unique to a node in the startup script.

Configure using

Configure using
System Properties





Yes, unless you use automatic naming




Yes, unless you use automatic naming




Yes, unless you use automatic naming


Your controller-info.xml file should now have values shown in the following sample configuration file:  


Automatic Naming for Application, Tier, and Node

For a self-service trial edition of AppDynamics Pro, the Agent Download Wizard doesn't prompt you for the application, tier or node name. It uses a default naming scheme instead (described in Instrument Java Applications).

You can use automatic naming with a standard edition of AppDynamics Pro by adding the following entry to controller-info.xml file:


Add the Java Agent as a javaagent Argument to the JVM

Add the Java Agent binary to the monitored process by adding a javaagent argument with the location of the Java Agent JAR file to the start-up script of the JVM:


Installing the agent with the javaagent argument requires a restart of the JVM. If it's not possible or convenient to restart the JVM when performing the configuration, you can attach the agent to the running process, as described in the following section.  

Use the server-specific instructions below to add this argument for different application server JVMs:

Attach 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). 

A few other points to consider are:

  • Do not attach the agent dynamically to an environment that is already instrumented (either by the AppDynamics Java Agent or another type other 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: 

  1. Determine the PID of the JVM to which you want to attach. For example, on Linux, use:

    ps -A | grep java

    On Windows, use: 

    jps -l
  2. Run the following command, replacing the placeholders for the path to the tools.jar file 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>

    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 [6780]
    agent path >>>/home/appduser/appagent/javaagent.jar

Verify Installation

After a successful install, your agent logs, located at <agent_home>/logs, should 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. 

Additional Installation Scenarios

Refer to the links below for typical installation scenarios, especially for cases where there are multiple JVMs on the same machine:


  • No labels