How to instrument a Java application with AppDynamics?

Agent is a vital part of Appdynamics framework. It is the agent that acts like a workhorse to pull metrics from the Application and push it to the Controller. Agent is a piece of software that is installed ON your application. The only function of the agent is to pull the monitoring metrics and send them to the AppDynamics Controller where the data is crunched and made available via the Controller UI. Note that there is NO need of a code change in your application. There is however a setup/configuration change required depending on the platform. In this article, I will explain how to instrument a Java Application.

What you need?

1. A working AppDynamics Controller. If you have not installed and configured your AppDynamics Controller, do that first.
2. Java Agent software which can be downloaded using the Agent Download Wizard on the Controller. Alternatively, it can also be downloaded from https://download.appdynamics.com. Note that the Agent is specific for the JVM vendor. For example, you cannot install Agent meant for IBM JVM on a JRockit JVM. (For more information on using the agent download wizard, see my free 15 minutes introduction to AppDynamics guide)
3. Location of the start script of your application. This varies depending on the Application Server (if any) you are using.
4. Account name and Account Access key. You will receive this information as part of software procurement.

Check firewall setup

The Java agent must be able to talk to the AppDynamics controller at port 8090. You can easily check this by using the following command from the server on which the Java application to be instrumented is running

telnet <AppDynamics Controller hostname or IP address> 8090

If you get a ‘Connection refused’, there is probably a Network/Firewall issue. A successful telnet will simply result in a blank screen waiting for your input.

Note that if you plan to use SSL for the Controller communication, the default port is 8181.

Ensure Permissions

The Agent runs as part of the JVM, meaning the agent executes inside the JVM. The user running the JVM (the user that starts the application) should have write access to the AppDynamics agent ‘conf’ directory and ‘logs’ directory.

Copy the Agent files and configure

Unzip the Agent software into a directory outside of your JVM. Update <Agent Home>/<version>/conf/controller-info.xml as follows

Note: If you had downloaded the agent via the agent download wizard from the controller, most of the information is already populated for you.

1. Controller host and port (Note that for Non-SSL, the default port number is 8090 and for SSL is is 8181)
2. Controller-ssl-enabled flag to be set to true or false
3. Application-name, tier-name and node-name

Sample configuration information is shown below:

<controller-info>

<controller-host>192.168.1.10</controller-host>

<controller-port>8090</controller-port>

<controller-ssl-enabled>false</controller-ssl-enabled>

<application-name>Production</application-name>

<tier-name>MoviesNet</tier-name>

<node-name>RecommendationEngine</node-name>

</controller-info>

Note that you can override some of the values above with java command line options as well. For example: -Dappdynamics.agent.nodeName=ReviewsEngine

Load the Agent

While the process for loading the agent differs from platform to platform, it is essentially adding the following system property to the java command line arguments

-javaagent:<agent_home>/javaagent.jar

If you are using a JEE Application Server such as Oracle WebLogic or IBM Websphere, locate the startup arguments (mostly configurable via Admin console or the start script) and update it as above.

Restart the JVM

This is required for the agent to load. As the agent loads, you should see the following log files in the <Agent home>/<version>/logs directory

Agent.<datetime>.log

ByteCodeTransformer.<datetime>.log

Browse through the agent.<datetime>.log to make sure there are not exceptions/errors.

If everything went fine, you will see the new node appear in the Controller UI (under the Application and Tier you had configured in the configuration file).

Note that you can attach the agent to a running JVM dynamically (available only on Oracle HotSpot JVM 1.6 + ). But I don’t recommend this (there is considerable performance hit when the agent is dynamically attached).

Can I automate the Java agent install?

You bet. What I have explained above is the manual way of instrumenting the agent. It is ok for few JVMs. But what if you need to instrument hundreds of JVMs (or even thousands)? There are few ways to achieve this. I’ll explain in an another article (Do I hear chef recipes somewhere?)

One final note: If you have multiple JVMs running on the same physical server, use one controller-info.xml and configure node specific properties in the Java command line arguments.

Happy Monitoring !!