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

Skip to end of metadata
Go to start of metadata

On this page:

Related pages:

Installing the Java Agent adds the agent to the JVM of the monitored application. 

Installation Overview

An overview of the steps are: 

  1. Download the agent software to the application machine
  2. Configure agent settings, and
  3. Add the agent into the JVM process

This topic takes you through the steps for downloading and installing the Java Agent manually using the agent configuration file. For more configuration options, see Java Agent Configuration Properties.

Planning for Java Agent Installation

When deciding where to put the Java Agent files, there are a few things to consider. The user under which the JVM runs must have write privileges to the conf and logs directories in the Java Agent home. To achieve this, you can install the agent as the same user that owns the JVM or as an administrator on the host machine. The rest of the contents of the agent directory can be restricted to read only access.  

The AppDynamics Java Agent is one type of bytecode injection agent. While the Java agent can run alongside other BCI agents on a JVM, you should thoroughly test your deployment in a staging environment to detect conflicts with other agents. Other agents can potentially interfere with the Java Agent class transformation process. To avoid potential issues, deploy the Java Agent as the only BCI agent on the JVM. 

This page describes basic installation. To configure the Java Agent to use SSL, also see Java Agent Configuration Properties and Enable SSL (Java)For a Java Agent that connects to the Controller through a proxy, see proxy configuration settings in Java Agent Configuration Properties.

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, as described ... 

Alternatively, you can download the agent manually, as follows: 

  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. Note the following:
    • Extract the Java Agent to a directory that is outside of your container or application server runtime directories, such as to \usr\local\appdynamics\appagent.
    • All files should be readable by the user under which the JVM runs. The user must have write privileges to the conf and logs directories in the Java Agent home. One way to achieve this is to install the agent as the same user that owns the JVM or as an administrator on the host machine.  
    • The application server's runtime directory should be writable by the Java Agent as well.

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 UI, you can jump ahead to the next section, as the agent is already configured.

To configure the settings manually (or verify the wizard settings): 

  1. In the agent home directory, open the following file for editing: 
    The controller-info.xml is one of several approaches available for supplying configuration settings. For others, see Java Agent Configuration Properties.      
  2. Find and modify the connection settings to the Controller: 
    • controller-host: Set to the IP address or hostname of the Controller. If the agent needs to connect through a proxy, see ... 
    • controller-port: Set to the primary listening port number on the Controller. By default, these are: 
      • For a SaaS Controller, use 80 for HTTP or 443 for HTTPS

      • For an on-premise Controller, use 8090 for HTTP or 8181 for HTTPS   

  3. Direct the agent to connect to the Controller by SSL (HTTPS) by setting the controller-ssl-enabled value to true. 
  4. Identify the business application, tier, and node that this the monitored JVM belongs to in the AppDynamics application model using these settings:
    • application-name 
    • tier-name 
    • node-name 

    In a self-service Trial edition of AppDynamics Pro, the agent uses a default naming scheme (as described in Instrument Java Applications). You can use automatic naming with a standard edition of AppDynamics Pro by adding the following property: 

  5. If the agents connects to a SaaS Controller or an on-premise Controller with multi-tenancy enabled, configure the Account Name and Account Key settings. If the agent connects to a single-tenant on-premise Controller only the Account Key is required.
    1. account-name 
    2. account-access-key 
    This information is provided in the Welcome email from the AppDynamics Team when you acquired the Controller. For a multi-tenant on-premise Controller, you can find this information in
  6. Configure any other properties desired. For a complete list, see Java Agent Configuration Properties

The following shows a controller-info.xml file with sample configuration values:  


Load the Java Agent in a JVM

After configuring the agent settings, you can add the agent to the JVM. The exact steps for doing so vary by framework. The general approach, however, involves specifying the agent as a ‑javaagent argument to the startup command for the JVM. 

 The argument should indicate the location of the Java Agent JAR file:


On Windows, include the drive letter in the path to the agent:


Adding the 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 Java Server-Specific Installation Settings 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 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 Java Agent Installation

After a 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.