To monitor Java applications in the Controller, you need to install the AppDynamics Java Agent on each server that hosts applications to be monitored. You then add the Java Agent binary to the Java application process, typically by passing the agent JAR file as a startup argument to the application. This enables the agent to instrument your application and report performance data to the AppDynamics Controller.
The following steps provide an overview of how to install the Java Agent using the Agent Download Wizard in the Controller. If you downloaded the agent from the AppDynamics Download Center, see Install the Java Agent.
Before You Begin
- Verify support for your application environment at Java Supported Environments.
- Confirm the connections settings to the Controller where your agent will report data:
- For a SaaS controller, AppDynamics sent you the Controller host in your Welcome Email.
- For an on-premise controller, the host and port for the Controller are configured at installation time.
- You will need to access the machine where the application runs as a user with privileges to install the agent software and restart the application. Verify that you have a user account with these privileges.
- Verify that the application machine can connect to the Controller. Proxies or firewalls in the network between the agent and Controller may require additional configuration.
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 resource allocated to it.
For network bandwidth consumption, see Install and Administer Agents.
Configure and Download the Java Agent
The Agent Download Wizard takes you through the steps for configuring and downloading the Java Agent. The wizard presents a few choices, including the type of JVM type (Sun or JRockit or IBM JVMs) of the application you want to monitor and whether it needs to connect to the Controller with SSL. For SSL, enter the SSL port to use (AppDynamics SaaS instances uses port 443 for SSL).
The wizard takes you through a slightly different flow for a self-service trial edition of the Controller versus a non-trial edition:
- For the self-service Pro Trial edition of AppDynamics Pro, the application and tier names are generated for you and not shown as entries in the wizard. This helps you get started quickly. You can always change these values after you understand how you want to model your environment in AppDynamics. See the following section for the automatic-naming format.
- For a non-trial edition, configure the application to which the agent will report data and the tier to which the node belongs in the wizard. A node name, the value that identifies an individual JVM in the monitored environment, is generated and inserted into the agent configuration automatically.
When specifying an application name, keep in mind that this value identifies the business application in the AppDynamics model of your environment to which this agent will report data. Conceptually, an AppDynamics business application does not necessarily correspond to the notion of an application in the monitored environment, where the application is usually thought of, for example, as a WAR file deployed to an application server. A single business application in AppDynamics may contain multiple applications in the monitored environment. For more information about modeling your environment in AppDynamics, see AppDynamics Concepts.
Each monitored JVM must have a unique node name in AppDynamics. This means that you need to run the wizard for each JVM to monitor, or, after downloading the agent, edit the configuration file that specifies the agent naming properties, controller-info.xml, to at least change the node name value before copying it to other machines.
Automatic Naming with a Self-Service Pro Trial
If you are using a self-service trial edition of AppDynamics Pro, AppDynamics names your application, tier, and node dynamically. AppDynamics uses the following naming scheme to identify agents that do not otherwise identify themselves in controller-info.xml or using startup arguments to the JVM:
- Application name: MyApp
- Tier name: MyTier
- Node name: <app_server_type>@<hostname>:<port> (for example: JBoss@appserver1.example.com:8080)
The automatically generated node name includes the port number that the server listens on. By using the listening port number in the node name, automatic naming ensures that when there are multiple instances of an application server on a single machine, all instances have unique node names.
Note that the port number used in the node name may not be the primary listening port for the server. If a server listens on multiple ports, automatic naming uses the lowest numbered port in the node name. For example, if a server uses port 8080 as a primary HTTP port but listens for shutdown requests on port 8005, the node will be named with the 8005 port.
For tiers, the Controller automatically recognizes distinct logical tiers based on traffic flow between the nodes and associates the nodes to individual tiers accordingly. All tiers belong to a single business application, MyApp. As you learn more about how you want to organize your applications in AppDynamics, you can change the names of nodes, tiers, or business applications in the Controller UI or in the configuration.
Download and Install the Agent in the JVM
After you download the agent, install it to your app server. The final window of the Agent Download Wizard includes brief instructions for installing the agent.
Log on as an administrator to the machine running your Java application. Unzip the AppServerAgent.zip file.
For example, on Linux unzip the agent to
home/appdynamics. This is the <agent_home> directory.
Edit your startup configuration file to include the Java Agent.Show more information on startup scripts...
View Application Activity in the Controller
Now you're ready to restart your application and view data in the Controller UI:
- Restart the JVM.
- Apply load to your application.
- Log on to the Controller to see your application in action.
The agent instruments the application code and reports metrics back to the Controller.
From here, you can install more agents or you can begin monitoring your application environment.