On this page:
Search App Agent Installation topics:
Instrumenting an application adds the AppDynamics application agent (app agent) into the runtime process of the application. This page gives you an overview of installing agents in the application environment.
Agent Installation Quick Start
The Getting Started Wizard in the AppDynamics Controller walks you through the steps to download and configure an agent for your application. This section gives you an overview of how to use the wizard.
The wizard produces a fully configured agent, including a node identity. Accordingly, it is intended to be run for each application instance you want to monitor, until you have the hang customizing the configuration manually.
Before trying to install an agent, you should check that:
- The agent supports your application environment.
- You have access the machine where the application runs with a user account with privileges to install the agent and—for more installation types—restart the application.
- The machine where the application runs can connect to the Controller. Proxies or firewalls on the network between the agent and Controller may require additional configuration.
Use the Getting Started Wizard
After verifying the requirements, follow the workflow as guided by the wizard:
- Open the wizard from the home page in the controller UI by clicking Getting Started.
- Enter the configuration values for the application instance as described in the wizard. You name the node and indicate the tier and business application to which it will belong. If you're not sure of the best values to use, you can use temporary names and change them later.
- When finished, download the agent. How you download the agent varies by agent type. In most cases, the agent comes as a ZIP file that you extract and install in the startup routine of your server. For other types of agents, you may need to modfiy the instrumented source code, for example, by including the agent library. The wizard walks you through it for each agent type.
- Install the agent on your app server.
- Apply load to your application. If you are instrumenting a production application, this will happen with customer interaction. Otherwise, create some test load on your application. The agent instruments the application code and reports metrics back to the Controller.
- View your application in the Application Dashboard, for example:
The wizard makes it easy to perform a basic installation of the agent with minimal required settings, such as the controller host and port, SSL, application name, and tier name. For advanced options or more complicated scenarios, you need to perform a manual installation of the agent. For more information, see the agent-specific link in the following section.
Agent Installation by Type
For detailed installation information by agent type, see the following topics:
For automated deployment guidelines, see Controller Deployment.
Tier and Node Naming Guidelines
The maximum length of a tier name is 100 characters and the maximum length of a node name is 500 characters. In your tier, node and application names, you should avoid certain special characters. The characters you can use are listed on the Tiers and Nodes page.
While node names do not need to be unique within a business application, the combination of tier and node name must be unique for the business application. Put another way, a tier cannot have two nodes with the same name. The tier names in a business application must also be unique.
Regardless of business application or tier membership, multiple nodes on a given machine must have unique node names. It should be very rare for two different applications to re-use the same node names on a single machine. However, this can happen in test environments or if two instances of the App Agent are accidentally started for the same node, and one instance is misconfigured to a different application.
To rename an application, tier, or node, see Interacting with Flow Maps.
App Agent Network Bandwidth Usage
The following guidelines can help you estimate how much bandwidth overhead will be added to your environment by deploying AppDynamics agents.
Keep in mind that the exact bandwidth required for a deployment varies greatly depending on the nature of your application, the agent configuration, and the AppDynamics features you use. The best way to determine the bandwidth overhead is to test the AppDynamics deployment in a staging environment that mirrors as closely as possible the live operating environment.
- The approximate bandwidth used by a single Java Agent with the default configuration is 5 to 8 kilobytes per second.
- Scaling of additional agents is linear. That is, if the average bandwidth usage for an app agent in a given deployment is 5 kilobytes, adding 10 means that bandwidth usage will be 5 × 10, or 50 kilobytes.
- While the average bandwidth used is 5 to 8 kbytes per second, agents send data to the Controller in bursts rather than as a steady stream of data. When testing bandwidth usage, to determine the actual kbytes per second used by an agent, you need to observe and average out traffic over the course of at least several minutes.
- When testing bandwidth usage in the environment, keep in mind that different types of tiers will generate a different amount of load. For instance, a database tier tends to generate more traffic between the agent and Controller than an application server tier. For the best possible estimate, the test should take this into account.
Agent License Considerations
For agent-based license units (including APM, database monitoring, and server monitoring), licenses are allocated to the first agents that register with the Controller up to the licensed limit. For example, with five agent licenses, the first five agents that connect to the Controller are licensed.
Agent licenses are not bound to a particular machine or application. Therefore, a transfer of an agent-based license can be done simply by shutting down the application that runs the licensed agent (uninstalling the agent if the application will need to be restarted) and starting up the new application with the newly installed agent. Once the agent disconnects, a license unit is freed for the second agent.
For application monitoring agents (Java, .NET, Node.JS, and so on), a license validation cycle runs every five minutes. It causes the agents to connect and validate that available license units are not exceeded. Historical usage data is captured during this cycle and stored as 5-minute usage data. Every hour, the 5-minute usage data is rolled up in hour usage data, which includes data on license unit usage. The five-minute data is purged after a few hours.