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 Deploy Analytics Without the Analytics Agent 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:

  1. Obtain a separate Application Analytics license. 
    See Application Analytics Licenses for more information.
  2. Enable the Analytics Agent.
  3. 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.
  4. 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. The Analytics Agent requires JRE 1.8 or later. 

For detailed information for installing the app server agents, see the following topics: 

Install Analytics Agent on Windows

As described in Deploy Analytics Without the Analytics Agent, 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, the 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

  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) 
    • 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. 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.

  3. If you are collecting log information on this host, you need to:

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

  1. Open the <analytics-agent-home>/conf/analytics-agent.properties file using a text editor. 

  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>

    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 Issues topic. 

      For on-premises installations use whatever host and port you have configured. In clustered environments, this is often a load balancer. 

  3. 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=<controller_host_name>:<http-listener-port>

    This is the URL and the port number you use to access the Appdynamics browser-based user interface. 

  4. Note down the Global Account Name and Access Key values found on the View License UI of the Controller.

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

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

  7. If you are collecting log information on this host, you need to:

Starting and Stopping the Analytics Agent

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

  1. Start the agent service:

    bin\analytics-agent.exe service-start

  2. 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 an environment variable named appdynamics.analytics.agent.url as follows:

  1.  On your Windows machine, go to System Properties > Advanced system settings > Environment Variables.

  2. 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.
  3. 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. 
  4. 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 Deploy Analytics Without the Analytics Agent, 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. 

  1. Confirm that JRE 8 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 available on the host.

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

  3. 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 8 or higher  -->
    <enabled>true</enabled>
...

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

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

  6. Note down the Global Account Name and Access Key values found on the View License UI of the Controller.

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

  8. If you are collecting log information on this host, you need to:

  9. Save and close the file.  

  10. 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, the 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:

  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 Linux, Solaris, and OSX
    • lib: contains all the jar files that need to be in the classpath
    • conf: contains all the configuration files, such as the properties and vmoptions files

  2. Open the following file to configure connectivity from the Analytics Agent to the Events Service.

     

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

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

  4. Note down the Global Account Name and Access Key values found on the View License UI of the Controller.

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

  6. If you are collecting log information on this host, you need to:

  7. Save and close the file.  

  8. 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:

  1. 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/

  2. Create a directory for the Analytics Agent in a writeable file system. 

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

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

  4. Create a writeable conf directory under that top-level directory.

    cd /tmp/analytics-agent-writable
mkdir conf
chmod 755 conf/
cd conf

  5. Create symlinks to the contents of the conf 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
  6. Create logs directory under analytics-agent-writable directory

  7. Run the Analytics Agent from the writable directory.

    cd /tmp/analytics-agent-writable
nohup bin/analytics-agent.sh start &

The resulting directories look similar to:

/tmp/
dr-xr-xr-x  6 ec2-user ec2-user 4096 Jul 17 20:45 analytics-agent-readonly
drwxr-xr-x  4 ec2-user ec2-user 4096 Jul 26 20:17 analytics-agent-writable

 /tmp/analytics-agent-writable/
total 24
drwxr-xr-x . . . 4096 Jul 27 19:41 .
drwxrwxr-x  . . .  4096 Jul 27 19:37 ..
lrwxrwxrwx 1 . . .   50 Jul 27 19:38 bin -> /tmp/analytics-agent-readonly/bin/
drwxr-xr-x . . .  4096 Jul 27 19:41 conf
lrwxrwxrwx . . .  50 Jul 27 19:38 lib -> /tmp/analytics-agent-readonly/lib/
drwxrwxr-x . . . 4096 Jul 27 19:41 logs
lrwxrwxrwx . . .   57 Jul 27 19:38 monitor.xml -> /tmp/analytics-agent-readonly/monitor.xml


conf/
total 20
drwxr-xr-x . . . 4096 Jul 27 19:41 .
drwxr-xr-x . . . 4096 Jul 27 19:41 ..
lrwxrwxrwx . . .   77 Jul 27 19:39 analytics-agent.properties -> /tmp/analytics-agent-readonly/conf/analytics-agent.properties
lrwxrwxrwx . . .   76 Jul 27 19:39 analytics-agent.vmoptions -> /tmp/analytics-agent-readonly/conf/analytics-agent.vmoptions
lrwxrwxrwx . . .  56 Jul 27 19:40 grok -> /tmp/analytics-agent-readonly/conf/grok/
lrwxrwxrwx . . .  55 Jul 27 19:39 job -> /tmp/analytics-agent-readonly/conf/job/
drwxrwxr-x . . . 4096 Jul 27 21:32 watermark

Tune Analytics Agent

This section describes the post-installation configuration of the Analytics Agent. You learn to configure Analytics Agent to connect to an 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: 

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

  3. 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 on resource usages, such as CPU usage, disk, and network I/O. The property is ad.max.runnable.sources and is found in the <analytics-agent-home>/conf/analytics-agent.properties file. By default ad.max.runnable.sources 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.


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.