Installing Agent-Side Components

See Analytics Deployment Options to review the deployment options and the agent-side component architecture.

• To collect log data, the machine must have either a Standalone Machine Agent or the Analytics Agent (standalone binary).
• To collect log and transaction data, the machine must have either a Standalone Machine Agent or the Analytics Agent (standalone binary) and Analytics enabled on the Controller.
• To collect only transaction data, the machine must have an app server agent with Analytics enabled on the controller. It must also have access to a Standalone Machine Agent or the Analytics Agent (standalone binary)  somewhere in the environment.

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, there are probably agents in your environment. To access the Analytics functionality, the app server agent must be version 4.0 or later. For detailed installation information for the supported app server agents, see the following topics: 

• Java Agent
• .NET Agent
• Node.js Agent

The Analytics Agent is not enabled by default. To use Application Analytics, you must:

• Obtain a separate Application Analytics license. See Application Analytics Licenses for more information.
• Enable the Analytics Agent.
• Enable Analytics on the Controller.

Changing Java Virtual Machine Options (Standalone Analytics Agent Only)

If you need to change any JVM start-up options, use a text editor to modify <analytics-agent-home>/conf/analytics-agent.vmoptions. Note that the vmoptions file name is read from the properties file: ad.jvm.options.name=analytics-agent.vmoptions. So, if you change the vmoptions file name then you need to change this 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.

Enable Analytics Agent as Standalone Machine Agent Extension

The Analytics Agent is implemented as an extension to the Standalone Machine Agent (and runs as a machine agent monitor). In environments with the Standalone Machine Agent already running, you enable and run the Analytics Agent as an extension. Use the following steps:

1. On the host running the Standalone Machine Agent, use a text editor to open <machine-agent-home>/monitors/analytics-agent/monitor.xml.

2. Set the enabled tag to true as follows, saving 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>
   ...

3. Configure connectivity from the analytics-agent to the Events Service by editing the analytics-agent.properties file: 

   <machine-agent-home>/monitors/analytics-agent/conf/analytics-agent.properties

4. In the analytics-agent.properties file, 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. If your firewall rules use IP addresses, review the Section "Firewall Considerations" in this topic: 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. 

5. Configure the account name and access key where the agent should publish data. Use the Global Account Name and Access Key values found on the View License UI of the Controller. For example:
   

   # The account in the Controller with which this Analytics data is associated.
   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. It is viewable on the License screen in the Controller as shown in the following screenshot:

   

6. 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.

7. Save and close the file.  

8. If the machine-agent is already running at this point, it needs to be restarted to pick up the changes in the configuration.
   

Enable the Analytics Agent as Standalone Binary

For installations on Windows machines or other environments that don't have a Standalone Machine Agent installed, you can install the Analytics Agent as a separate binary. The Analytics Agent is written in Java, so you run it in a JVM. As described in Analytics Deployment Options, the Analytics Agent can run on the same host or on a different host from the monitored applications, depending on your use case. The download site provides downloads as follows:

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

To install the Analytics Agent as a Windows service

1. 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) and the script for Linux (.sh) 
   • 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

2. Follow the steps to revise the properties file. Note that analytics-agent.properties file is found in <analytics-agent-home> directory in this case.

   <analytics-agent-home>\conf\analytics-agent.properties

3. 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.

4. Save and close the file.

5. 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. 

6. Start the service using the method of your choice as described below: To Start and Stop the Analytics Agent (.NET).

Revise the Analytics Agent Properties File

Follow these steps to revise the properties file. Note the differences in the location of this file depending on your exact deployment scenario. 

1. Use a text editor to open the properties file. The analytics-agent.properties file is found either in the <analytics-agent-home>/conf directory or under the <machine-agent-home>/monitors/ (in the case where your .NET Agent and the Standalone Machine Agent are running on the same machine).

2. 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>

   Where the host and port are either: https://analytics.api.appdynamics.com:443, for SaaS-based installations, or whatever host and port you have configured for on-premises installations, in clustered environments, often a load balancer. If your firewall rules use IP addresses, review the Section "Firewall Considerations" in this topic: Troubleshooting Analytics Agent Issues.

3. Configure the account and account key where the agent should publish data as the accountName and accessKey values. 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. It is viewable on the License screen in the Controller as shown in the following screenshot:
   

4. 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

     Note 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

5. (Optional) If you are collecting log information on this host, you need to update additional properties. See Configure Properties for Consolidated Log Management.

To enable the Analytics Agent using Standalone Machine Agent

In the case where you are running a .NET Agent and the Standalone Machine Agent on the same machine, it is not necessary to install a separate Analytics Agent. You can take advantage of the bundled analytics extension to the Machine Agent. Use the following steps:

1. Confirm that you are running the Standalone Machine Agent and the .NET Agent, on the same machine. 

2. On each host where the Standalone Machine Agent is deployed and you want to enable the Analytics Agent,  use a text editor to open <machine-agent-home>/monitors/analytics-agent/monitor.xml and set the enabled tag to true as follows, saving 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>
   ...

   
   

3. Follow the steps to revise the properties file. Note that analytics-agent.properties file is found under the machine agent install directory in this case.
   

   <machine-agent-home>\monitors\analytics-agent\conf\analytics-agent.properties

4. Save and close the file.

5. If you are collecting log information on this host, configure log analytics. For details, see Collect Log Analytics Data.

To start and stop the Analytics Agent (Windows)

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

1. To start the agent service from the command line:
   

   bin\analytics-agent.exe service-start

2. To stop the agent service for the command line:

   bin\analytics-agent.exe service-stop

To uninstall the Windows service

Run the .exe file with the uninstall command as follows: 

bin\analytics-agent.exe service-uninstall

Configure Properties for Consolidated Log Management

The analytics-agent.properties file has new properties that need to be configured to work with Centralized Log Management (CLM). If you are using CLM to configure your log files with source rules, you need to provide these properties with the correct values. You should configure ad.controller.url, http.event.name and ad.agent.name.  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

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.

Verify Agent Start

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

Enabled Job Files Limit

To limit resource usage, there is a default limit on the number of job files that can be enabled 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.properties file. By default ad.max.enabled.jobs = 20.

Enable Analytics on the Controller

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

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

Configure the Analytics Agent for a Remote Host

The default settings assume that the Analytics Agent is on the same host and uses the same default port as your app server agent. If your Analytics Agent is on a host separate from the monitored application, or you have changed the default port, you need to specify the new host and port values.

For Java

 Specify the location of the remote Analytics Agent with a -D parameter to the JVM, 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.  

For Windows

Specify the location of the remote Analytics Agent with a environment variable as follows:

• Add a system environment variable named "appdynamics.analytics.agent.url" and set the value 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.
• 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. While it is not required that you restart your machine, the parent process that is invoking the monitored process must be restarted.

To add an environment variable, go to System Properties > Advanced system settings > Environment Variables.
 

Add a new environment variable as shown:

Connect to the Events Service through a Proxy (Optional)

In some environments you need to connect the Analyatics Agent to the Events Service through a proxy server.

1. Edit the properties file as follows:
   1. Java: Open <machine-agent-home>\monitors\analytics-agent\conf\analytics-agent.properties with a text editor.
   2. Windows: Open <analytics-agent-home>\conf\analytics-agent.properties with a text editor.

2. 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>

Run the Analytics Agent from a Read-Only Filesystem

This solution applies to Linux installs for version 4.3.5 and later. To install and run the Analytics Agent from a read-only filesystem, 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 Analytics Agent in the read-only file system. The end result is 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

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

mkdir /tmp/analytics-agent-writable
cd /tmp/analytics-agent-writable

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
mkdir conf
cd conf
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

Watch the Video

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