Installing Agent-Side Components

On this page:

In all AppDynamics Application Analytics deployment scenarios, you must enable the Analytics Agent-side components. The Analytics Agents are distributed as operating system-based or standalone bundles which you can download from the AppDynamics Releases page. This section describes different scenarios of setting up each component of Application Analytics to collect business transaction data.

Prepare to Enable the Agents

Review the deployment options and the agent-side component architecture in Analytics Deployment Options to confirm which components you need to install.

Analytics Agent

The Analytics Agent collects data from AppDynamics App Agent (app server agent) and log files, and sends it to the Events Service. The Analytics Agent is not enabled by default. To use the Analytics Agent, you need to download the desired bundle and enable it using a method of your choice as described in this topic. To use Application Analytics, you must:

Obtain a separate Application Analytics license.
See Application Analytics Licenses for more information.
Enable the Analytics Agent.
Point to the Event Service.
See Revise the Analytics Agent Properties File for information on agent-specific configuration.
See Event Service Deployment for more information on Event Service.
Enable Analytics on the Controller.

AppDynamics App Agent

In all environments, to collect transaction data from an application, you must have a supported app server agent deployed. If you already use AppDynamics APM, agents might already be installed in your environment. To access the Analytics functionality, the app server agent must be version 4.0 or later. For detailed information for installing the app server agents, see the following topics:

Install Analytics Agent on Windows

As described in Analytics Deployment Options, the Analytics Agent can run on the same host or on a different host from the app server agent, depending on your use case. The AppDynamics Releases page provides the following distribution archives:

Standalone Analytics Agent (no JRE)
Analytics Agent with JRE 1.8 for both 32-bit and 64-bit Windows machines.

Enable Analytics Agent for a Local App Server Agent

This section assumes that you are installing the Analytics Agent on the same host as your app server agent. In this deployment, Analytics Agent reads and transmits log data from log files from the local machine. The app server agent transmits data from the monitored application to the Analytics Agent.

You install the Analytics Agent using the .exe file, analytics-agent.exe, found in the <analytics-agent-home>/bin directory. The Analytics Agent is written in Java, so you run it in a JVM. On Windows machines, the Analytics Agent runs as a Windows service.

Installing the Analytics Agent

Unzip the Analytics Agent distribution archive to the installation directory on each target host.
When you unzip this archive, you get three directories:
- bin: contains the binary file for Windows(.exe)
- lib: contains all the jar files that need to be in the class path
- conf: contains all the configuration files, such as the properties and vmoptions files
Configure the Analytics Agent by modifying the analytics-agent.properties file:
```
<analytics-agent-home>\conf\analytics-agent.properties
```
For more information on configuration instructions, see Revise the Analytics Agent Properties File.
If you are collecting log information on this host, you need to:
- Configure your log sources. See Collect Log Analytics Data for details.
- Update additional properties. See Configure Properties for Consolidated Log Management.
Save and close the file.
Run the following command to install the Analytics Agent as a service.
```
bin\analytics-agent.exe service-install
```
Now your analytics-agent can be managed like any other Windows service.
Start the service using the method of your choice as described in Starting and Stopping the Analytics Agent.

Revise the Analytics Agent Properties File

The Analytics Agent properties file determine how your Analytics Agent communicate with other components, what type of data it gathers from the monitored application, and how the components of the Application Analytics deployment and the Controller authenticate to each other. You modify the default configuration and set desired values for the agent properties by using the Analytics Agent properties file. Note the differences in the location of this file depending on your exact deployment scenario.

Open the <analytics-agent-home>/conf/analytics-agent.properties file using a text editor.
Change the default URL and, if necessary, the port number for the connection to the Events Service by modifying the http.event.endpoint value. For example:
```
http.event.endpoint=http://<events_service_host:events_service_port>
```
For SaaS-based installations, the host and port combination is one of the following:
- https://analytics.api.appdynamics.com:443 (North America)
- https://fra-ana-api.saas.appdynamics.com:443 (Europe)
- ```
https://syd-ana-api.saas.appdynamics.com/:443 (APAC)
```
  If your firewall rules use IP addresses, review the "Firewall Considerations" section in the Troubleshooting Analytics Agent Issues topic.
For on-premises installations use whatever host and port you have configured. In clustered environments, this is often a load balancer.
Change the default URL and the port number to point to the Controller by modifying the ad.controller.url property. For example:
```
ad.controller.url=<application_server_host_name>:<http-listener-port>
```
This is the URL and the port number you use to access the Appdynamics browser-based user interface.
Note down the Global Account Name and Access Key values found on the View License UI of the Controller.
Configure the account and account key for which the agent should publish the business transaction data. Use the Global Account Name and Access Key values you have collected earlier. For example:
```
# The global_account_name in the Controller for this analytics data, similar to the following:
http.event.accountName=<customer1_74678b04-8a71-40ef-acaf-xxxxxxxxxxxx>
# Replace this value with the access key of the account name configured above.
http.event.accessKey=<3d58aba2-xxx-xxx>
```
The http.event.accountName property specifies the Global Account Name of the account. The http.event.accessKey property specifies the Access Key, which provides an authentication mechanism between the Controller and the components of the Application Analytics deployment. The Controller installation process generates the Access Key value.
For SAAS-based installations, set the http.event.name property to Name of the account. The default value is customer1. If the property is not configured correctly, the Analytics Agent will not be able to authenticate. The resulting errors are stored in the analytics-agent.log file.
Change these properties, which are needed to run the Analytics Agent as a Windows service:
- ad.dw.log.path=<analytics-agent-home>\\logs
- conf.dir=<analytics-agent-home>\\conf
- ad.jvm.options.name=analytics-agent.vmoptions
- ad.jvm.heap.min=512m
- ad.jvm.heap.max=1g
  The Analytics agent on Windows requires double backslash for paths, for example:
```
conf.dir=C:\\AppD\\analytics-agent\\conf
ad.dw.log.path=C:\\AppD\\analytics-agent\\logs
```
If you are collecting log information on this host, you need to:
- Configure your log sources. See Collect Log Analytics Data for details.
- Update additional properties. See Configure Properties for Consolidated Log Management.

Starting and Stopping the Analytics Agent

You can use native Windows services menu to start and stop the service or you can do it directly from command line using the following commands.

Start the agent service:
```
bin\analytics-agent.exe service-start
```
Stop the agent service:
```
bin\analytics-agent.exe service-stop
```

Uninstalling Analytics Agent

At the command line, run the .exe file with the uninstall command as follows:

bin\analytics-agent.exe service-uninstall

Enable the App Server Agent for a Remote Analytics Agent

The default settings of the app server agent typically assume that the Analytics Agent is on the same host and uses the default port. If your Analytics Agent is on a host separate from the app server agent, as shown in the diagram below, or you have changed the default port, you need to specify the new host and port values for the app server agent.

On Windows, you specify the location of the remote Analytics Agent with a environment variable named appdynamics.analytics.agent.url as follows:

On your Windows machine, go to System Properties > Advanced system settings > Environment Variables.
Under System variables, click New.
Although you can also use a User environment variable, the user under which the environment variable is set must have the same permissions as the user under which all the instrumented apps are running. To avoid issues with this, we recommend using a System environment variable approach.
Set the value for the appdynamics.analytics.agent.url Sytem Variable to http://<analytics-agent-ip>:9090/v2/sinks/bt.
Replace <analytics-agent-ip> with the hostname of the Analytics Agent for your environment.
Restart the applicable application or process where you want the new environment variables to take effect.
For w3wp in Windows, restart IIS by running iisreset after the changes are made to the environment variables.
While it is not required that you restart your machine, the parent process that is invoking the monitored process must be restarted.

Install Analytics Agent on Linux

As described in Analytics Deployment Options, the Analytics Agent can run on the same host or on a different host from the app server agent, depending on your use case. The AppDynamics Releases page provides the following distribution archives.

Standalone Analytics Agent (no JRE)
Machine Agent Bundle - 64-bit osx (zip)
Machine Agent Bundle - for both 32-bit and 64-bit Linux machines (rpm)
Machine Agent Bundle - for both 32-bit and 64-bit Linux machines (zip)
Machine Agent Bundle - for 64-bit solaris (zip)
Machine Agent Bundle - for 64-bit solaris-sparcv9 (zip)
Machine Agent Bundle - for 64-bit solaris-x64 (zip)

Enable Analytics Agent as an Extension to Standalone Machine Agent

If the Machine Agent and app server agent are running on the same machine, installing a Standalone Analytics Agent is not necessary. In environments with the Standalone Machine Agent already running, you enable and run the Analytics Agent as an extension. This section describes how to configure the Analytics Agent as an extension to the Standalone Machine Agent and run as a machine agent monitor.

Confirm that JRE 7 or higher is installed on the host running the Standalone Machine Agent.
Analytics Agent cannot be enabled if the required version of JRE is not avaible on the host.
On the host running the Standalone Machine Agent, open <machine-agent-home>/monitors/analytics-agent/monitor.xml using a text editor.

Set the enabled tag to true as follows and save the file when you are finished.

<monitor>
    <name>AppDynamics Analytics Agent</name>
    <type>managed</type>
    <!-- Enabling this requires JRE 7 or higher  -->
    <enabled>true</enabled>
...

Open the following file to configure connectivity from the Analytics Agent to the Events Service.
```
<machine-agent-home>/monitors/analytics-agent/conf/analytics-agent.properties
```
In the analytics-agent.properties file, do the following:
- Change the default URL and, if necessary, the port number for connecting to the Events Service by modifying the http.event.endpoint value. For example:
```
http.event.endpoint=http://<events_service_host:events_service_port>
```
  For SaaS-based installations, the host and port are:
  - https://analytics.api.appdynamics.com:443 (North America)
  - https://fra-ana-api.saas.appdynamics.com:443 (Europe)
  - https://syd-ana-api.saas.appdynamics.com:443 (APAC)
    If your firewall rules use IP addresses, review firewall considerations in Troubleshooting Analytics Agent Issues.
  For on-premises installations use whatever host and port you have configured. In clustered environments, this is often a load balancer.
- Change the default URL and the port number to point to the Controller by modifiying the ad.controller.url property. For example:
```
ad.controller.url=http://<application_server_host_name>:<http-listener-port>
```
  This is the URL and the port number you use to access the Appdynamics browser-based user interface.
Note down the Global Account Name and Access Key values found on the View License UI of the Controller.
Configure the account and account key for which the agent should publish the business transaction data. Use the Global Account Name and Access Key values you have collected earlier. For example:
```
# The global_account_name in the Controller for this analytics data, similar to the following:
http.event.accountName=<customer1_74678b04-8a71-40ef-acaf-xxxxxxxxxxxx>
# Replace this value with the access key of the account name configured above.
http.event.accessKey=<3d58aba2-xxx-xxx>
```
The http.event.accountName property specifies the Global Account Name of the account. The http.event.accessKey property specifies the Access Key, which provides an authentication mechanism between the Controller and the components of the Application Analytics deployment. The Controller installation process generates the Access Key value.
For SAAS-based installations, set the http.event.name property to Name of the account. The default value is customer1. If the property is not configured correctly, the Analytics Agent will not be able to authenticate. The resulting errors are stored in the analytics-agent.log file.
If you are collecting log information on this host, you need to:
- Configure your log sources. See Collect Log Analytics Data for details.
- Update additional properties. See Configure Properties for Consolidated Log Management.
Save and close the file.
If the machine-agent is already running at this point, restart it to pick up the changes in the configuration.

To connect to the Events Service through a proxy server, see Connect the Agent to the Events Service through a Proxy.

Enable Standalone Analytics Agent

In this deployment, Analytics Agent and app server agent are running on the same machine. Analytics Agent reads and transmits log data from log files on the host machine. The app server agent transmits data from the monitored application to the Analytics Agent.

For environments that don't have a Machine Agent installed, install the Analytics Agent as a separate binary, analytics-agent.sh:

Unzip the Analytics Agent distribution archive to the installation directory on each target host.
When you unzip this archive, you get three directories:
- bin: contains the binary file for Linux, Solaris, and OSX
- lib: contains all the jar files that need to be in the class path
- conf: contains all the configuration files, such as the properties and vmoptions files
Open the following file to configure connectivity from the Analytics Agent to the Events Service.
```
<analytics-agent-home>/conf/analytics-agent.properties
```
In the analytics-agent.properties file, do the following:
- Change the default URL and, if necessary, the port number for connecting to the Events Service by modifying the http.event.endpoint value. For example:
```
http.event.endpoint=http://<events_service_host:events_service_port>
```
  For SaaS-based installations, the host and port are:
  - https://analytics.api.appdynamics.com:443 (North America)
  - https://fra-ana-api.saas.appdynamics.com:443 (Europe)
  - ```
  https://syd-ana-api.saas.appdynamics.com:443 (APAC)
```
  If your firewall rules use IP addresses, review firewall considerations in Troubleshooting Analytics Agent Issues.
  For on-premises installations use whatever host and port you have configured. In clustered environments, this is often a load balancer.
- Change the default URL and the port number to point to the Controller by modifiying the ad.controller.url property. For example:
```
ad.controller.url=http://<application_server_host_name>:<http-listener-port>
```
  This is the URL and the port number you use to access the Appdynamics browser-based user interface.
Note down the Global Account Name and Access Key values found on the View License UI of the Controller.
Configure the account and account key for which the agent should publish the business transaction data. Use the Global Account Name and Access Key values you have collected earlier. For example:
```
# The global_account_name in the Controller for this analytics data, similar to the following:
http.event.accountName=<customer1_74678b04-8a71-40ef-acaf-xxxxxxxxxxxx>
# Replace this value with the access key of the account name configured above.
http.event.accessKey=<3d58aba2-xxx-xxx>
```
The http.event.accountName property specifies the Global Account Name of the account. The http.event.accessKey property specifies the Access Key, which provides an authentication mechanism between the Controller and the components of the Application Analytics deployment. The Controller installation process generates the Access Key value.
For SAAS-based installations, set the http.event.name property to Name of the account. The default value is customer1. If the property is not configured correctly, the Analytics Agent will not be able to authenticate. The resulting errors are stored in the analytics-agent.log file.
If you are collecting log information on this host, you need to:
- Configure your log sources. See Collect Log Analytics Data for details.
- Update additional properties. See Configure Properties for Consolidated Log Management.
Save and close the file.
Install the Analytics Agent by running the following command.
```
bin\analytics-agent.sh start
```

Configure the App Server Agent for a Remote Analytics Agent

The default settings of the app server agent typically assume that the Analytics Agent is on the same host and uses the default port. If your Analytics Agent is on a host separate from the app server agent, as shown in the diagram below, or you have changed the default port, you need to specify the new host and port values for the app server agent.

Specify the location of the remote Analytics Agent with a -D parameter. The argument is passed to the monitored application as follows:

-Dappdynamics.analytics.agent.url=http://<analytics-agent-ip>:9090/v2/sinks/bt

Replace <analytics-agent-ip> with the hostname of the Analytics Agent for your environment.

Run the Analytics Agent From a Read-Only Filesystem

In this deployment, the Analytics Agent is installed and run from a read-only filesystem. To do so, you need to direct the Analytics Agent to write its log files to a writeable partition.

Create a directory for the Analytics Agent in a writeable file system and create symlinks to the contents of the analytics agent in the read-only file system, with the end result that you have a writeable top-level directory for the Analytics Agent and a writeable logs directory under that top-level directory.

To run analytics-agent from a separate writable directory using artifacts from a read-only directory:

Provide necessary permissions to the read-only Analytics Agent directory.

# analytics-agent-readonly refers to the read-only analytics agent.
chmod -R 555 /tmp/analytics-agent-readonly/

Create a directory for the Analytics Agent in a writeable file system.
```
mkdir /tmp/analytics-agent-writable
cd /tmp/analytics-agent-writable
```

Create symlinks to the contents of the analytics agent in the read-only file system.

ln -s /tmp/analytics-agent-readonly/bin/ bin
ln -s /tmp/analytics-agent-readonly/lib/ lib
ln -s /tmp/analytics-agent-readonly/monitor.xml monitor.xml

Create writeable logs directory under that top-level directory.
```
cd /tmp/analytics-agent-readonly
mkdir conf
cd conf
```

Create symlinks to the contents of the log directory.

ln -s /tmp/analytics-agent-readonly/conf/analytics-agent.* .
ln -s /tmp/analytics-agent-readonly/conf/job/ job
ln -s /tmp/analytics-agent-readonly/conf/grok/ grok

cd /tmp/analytics-agent-writable

The resulting directories look similar to:

/tmp/
dr-xr-xr-x   ...  238B Jun 13 16:03 analytics-agent-readonly
drwxr-xr-x   ...   238B Jun 13 17:06 analytics-agent-writable

 /tmp/analytics-agent-writable/
total 24
drwxr-xr-x  ...  238B Jun 13 17:06 .
drwxr-xr-x  ...   136B Jun 13 16:07 ..
lrwxr-xr-x  ...   131B Jun 13 16:11 bin -> /tmp/analytics-agent-readonly/bin
drwxr-xr-x  ...   238B Jun 13 17:03 conf
lrwxr-xr-x  ...  132B Jun 13 16:34 lib -> /tmp/analytics-agent-readonly/lib/
drwxr-xr-x  ...   170B Jun 13 17:06 logs
lrwxr-xr-x  ...    36B Jun 13 16:08 monitor.xml -> /tmp/analytics-agent-readonly/monitor.xml

conf/
total 32
drwxr-xr-x  ...   238B Jun 13 17:03 .
drwxr-xr-x  ...   238B Jun 13 17:06 ..
lrwxr-xr-x  ...   159B Jun 13 16:12 analytics-agent.properties -> /tmp/analytics-agent-readonly/conf/analytics-agent.properties
lrwxr-xr-x  ...   158B Jun 13 16:12 analytics-agent.vmoptions -> /tmp/analytics-agent-readonly/conf/analytics-agent.vmoptions
lrwxr-xr-x  ...   138B Jun 13 16:16 grok -> /tmp/analytics-agent-readonly/conf/grok/
lrwxr-xr-x  ...  137B Jun 13 16:15 job -> /tmp/analytics-agent-readonly/conf/job/
drwxr-xr-x  ...  136B Jun 13 17:06 watermark

Tune Analytics Agent

This section describes the post-installation configuration of the Analytics Agent. You learn to configure Analytics Agent to connect to a Event Service using a proxy server, to collect log files using Consolidated Log Management (CLM), to set resource usage limit, and to change Java Virtual Machine (JVM) options.

Connect to the Events Service through a Proxy

If the Analytics Agent needs to connect to the Events Service through a proxy server, do the following:

Open <analytics-agent-home>\conf\analytics-agent.properties with a text editor.

Add this information:

# optional proxy properties
http.event.proxyHost=<your proxy host>
http.event.proxyPort=<your proxy port>
http.event.proxyUsername=<your proxy username, if authentication is required>
http.event.proxyPassword=<your proxy password, if authentication is required>

Save and close the file.

Configure Analytics Agent for Consolidated Log Management

If you want your Analytics Agent to work with CLM you need to configure a few properties in the Analytics Agent properties file. You provide the Controller URL, customer name, and name of your Analytics Agent in the analytics-agent.properties file. The customer name is found on the View License UI of the Controller. If you are using CLM to configure your log files with source rules, you need to provide these properties with the correct values.

The default values are the following:

# Format should be http://<host>:<port>
ad.controller.url=http://localhost:8090

# The customer name field from the appdynamics license page.
http.event.name=customer1

# This is the friendly agent name that will show up in the controller when the agent registers and syncs configuration.
ad.agent.name=analytics-agent1

Changing Java Virtual Machine Options (Standalone Analytics Agent Only)

You do not need to modify JVM options if you bundle the Analytics Agent with the Machine Agent.

If you need to change any JVM start-up options, modify <analytics-agent-home>/conf/analytics-agent.vmoptions by using a text editor. Be aware that the vmoptions file name is read from the ad.jvm.options.name=analytics-agent.vmoptions properties file. So, if you change the vmoptions file name you need to change the ad.jvm.options.name property as well.

(Windows only) If the Analytics Agent Windows service is installed and you need to change the properties file or the vmoptions file, you need to uninstall the service and reinstall it for the changes to take effect.

Configure Resource Usage Limit

To limit resource usage, you can enable the default limit on the number of job for a single analytics agent. This limit can be overridden but is not recommended without a thorough understanding of the potential impact to resource usage, such as CPU usage, disk, and network I/O. The property is ad.max.enabled.jobs and is found in the <analytics-agent-home>/conf/analytics-agent.properties file. By default ad.max.enabled.jobs is set to 20.

Verify Analytics Agent Status

To verify that the Analytics Agent has started, you can look for the following entry in the App Agent log file: "Started [Analytics] collector"

If you need to connect to the Events Service through a proxy server, see Connect the Agent to the Events Service through a Proxy below.

Enable Analytics on the Controller

Once you have set up the Analytics Agent, you need to enable Analytics on the Controller.

In the Controller UI, select the Analytics tab.
Select Configuration.
From the Transaction Analytics tab, select the application you wish to monitor from the dropdown menu.
Check Enable Analytics Data Collection for <application_name>.

Troubleshooting Tips

Make sure that the properties in analytics-agent.properties are properly set. Also see Enabled Job Files Limit.
JRE version is >= 1.7 and JAVA_HOME variable is set in the environment.
All the properties in analytics-agent/conf/analytics-agent.vmoptions are compatible with the JRE.

Watch the Video

For full-screen viewing, click Getting Started with Transaction Analytics.