The AppDynamics App Agent for Java identifies and tracks business transactions, captures statistics and diagnostic data, and analyzes and reports data to the Controller. The App Agent for Java uses dynamic bytecode injection to instrument a JVM and it runs as a part of the JVM process.

Caution: The AppDynamics Agent for Java may fail if there are other Application Performance Management (APM) products installed in the same JVM.  They can coexist as long as the other APM does not interfere with the AppDynamics Agent for Java class transformations. We discourage the simultaneous use of other Byte Code Injection (BCI) agents.

Overview of the App Agent for Java Installation Process

Installing the App Agent for Java involves adding it as a javaagent (Java Programming Language Agent) on your JVM and setting up connection and identifying parameters for it to report data to the Controller.

Install the App Agent for Java as the same user or administrator of the JVM. Otherwise the agent may not have the correct write permissions for the system. The agent directories must have write permission so that AppDynamics can update the logs and other agent files.

Planning for Agent Installation

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

Important Files

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

• The -javaagent argument uses the fully-qualified path of the javaagent.jar file. No separate classpath arguments need to be added.

• The <agent_home>/conf/controller-info.xml file is where you add the configuration mentioned in the planning list.

To Install the Java App Server Agent

1. Download and unzip the App Agent for Java

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

Note: Do not unzip/install the agent into to the ..\tomcat\webapps directory. By default Tomcat tries to undeploy and deploy files under the webapps folder. To avoid the possibility that Tomcat will occasionally not restart, we recommend installing the agent to a directory outside of tomcat, such as \usr\local\agentsetup\AppServerAgent.

2. Add the agent properties as a 'javaagent' argument to your JVM

This step adds the agent to the startup script of your application server. Use the server-specific instructions below to add this argument for different Application Server JVMs:

3. Configure how the agent connects to the Controller

• Configure properties for the Controller host name and its port number.
• You can configure these two properties using either the controller-info.xml file or the JVM startup script:

Optional settings for Agent-Controller communication

• To configure the Java Agent to use SSL, see App Agent for Java Configuration Properties
  See Enable SSL (Java) for instructions on new SSL configuration in 3.7.6
• To configure the Java Agent to use proxy settings see App Agent for Java Configuration Properties

4. (Only for Multi-tenant mode or SaaS Installations): Configure Agent account information

• This step is required only when the AppDynamics Controller is configured in Controller Tenant Mode or when you Use a SaaS Controller.
  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.

5. Configure how the agent identifies the AppDynamics business application, tier, and node.

To better understand agents and how they relate to business applications, tiers, and nodes see
Logical Model and Name Business Applications, Tiers, and Nodes.

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.

-javaagent:<agent_home>/javaagent.jar=uniqueID=<my-app-jvm1>

Additional Installation Scenarios

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

• Configure App Agent for Java on Multiple JVMs on the Same Machine that Serves the Same Tier

• Configure App Agent for Java on Multiple JVMs on the Same Machine that Serve Different Tiers

• Configure App Agent for Java to Use Existing System Properties

• App Agent for Java on z-OS or Mainframe Environments Configuration

• Configure App Agent for Java for Batch Processes

• Add the Agent into an Embedded JVM

6. Verify agent configuration

• Ensure that you have added -javaagent argument in your JVM startup script. This is not a -D system property but a different standard argument for all JVMs v1.5 and higher.

• Ensure that you have added all mandatory items either in the Agent controller-info.xml file or in the JVM startup script file.

• The user running the JVM process/application server process is the user accessing the Java Agent installation.

7. Verify successful installation and reporting

a. Verify agent installation

After a successful install, your agent logs, located at <agent_home>/logs, should contain following message:

Started AppDynamics Java Agent Successfully

If the agent log file is not present, the App Agent for Java may not be accessing the javaagent command properties. The application server log file where STDOUT is logged will have the fallback log messages, for further troubleshooting.

b. Verify that the agent is reporting to the Controller

Use the AppDynamics UI, to verify that the Java Agent is able to connect to the Controller:

• Point your browser to: http://<controller-host>:<controller-port>/controller
• Provide the admin credentials to log into the AppDynamics UI.
• Select the application. In the left navigation pane, click Servers -> App Servers -> <tier> -> <node>. Click the Agents tab and App Server Agent subtab. An agent successfully reporting to the Controller will be listed and the Reporting property shows an "up" arrow symbol. For more details see Verify App Agent-Controller Communication.
• When deploying multiple agents for the same tier, see if you get the exact number of nodes reporting in the same tier.

Example Configuration: App Agent for Java Deployment on a Single JVM

The following example shows a sample deployment of the App Agent for Java for the ACME Bookstore.

• Add the javaagent argument to the start-up script of the JVM:

java -javaagent:/home/appdynamics/AppServerAgent/javaagent.jar

• Define the five mandatory items for agent configuration in the Agent controller-info.xml file:

<controller-info>
    <controller-host>192.168.1.20</controller-host>
    <controller-port>8090</controller-port>
    <application-name>ACMEOnline</application-name>
    <tier-name>InventoryTier</tier-name>
    <node-name>Inventory1</node-name>

</controller-info>

Learn More

• App Agent for Java Configuration Properties
• Uninstall the App Agent for Java
• Logical Model