This page applies to an earlier version of the AppDynamics App IQ Platform.
For documentation on the latest version, see the 4.4 Documentation.


On this page:

Your Rating:
Results:
PatheticBadOKGoodOutstanding!
61 rates
In all deployment scenarios, to use AppDynamics Application Analytics, you must enable the Analytics Agent-side components.This section describes the steps to set up each component. 

As described in Deployment Options and Scenarios, whether you enable one or many Analytics Agents for your deployment depends on your requirements.

  • To collect log data, the machine must have either a Standalone Machine Agent (Java) or the Analytics Agent (.NET) deployed.
  • To collect log and transaction data, the machine must have either a Standalone Machine Agent or the Analytics Agent deployed and Analytics enabled on the controller.
  • To collect only transaction data, the machine must have an App Agent with Analytics enabled on the controller. It must also have access to a Standalone Machine Agent (Java) or the Analytics Agent (.NET)  somewhere in the environment.

Select the components you need based on your requirements. 

 In all environments, to collect transaction data from an application, you must have deployed an appropriate app agent. If you already use AppDynamics APM, there are probably app agents in your environment. To access the Analytics functionality, the app agent must be version 4.0 or later. See Instrument Java Applications and Instrument .NET Applications for more information.  

(info) The Java App Agent and the .NET App Agent are often simply called the Java Agent and the .NET Agent elsewhere in the documentation.  "App" is added here only for clarity.  

Enable the Analytics Agent

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

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

Enable the Analytics Agent (Java)

The Analytics Agent is implemented as an extension to the Standalone Machine Agent (and runs as a machine agent monitor). In Java environments, use the following steps:

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

  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 following 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 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 are https://analytics.api.appdynamics.com:443. If your firewall rules use IP addresses, review the Section "Firewall Considerations" in this topic: Troubleshooting.
    For on-premise installations use whatever host and port you have configured. In clustered environments, this is often a load balancer. 

  5. Configure the account and account key where the agent should publish data as the accountName and accessKey values. For example:

    # The account in the Controller with which this Analytics data is associated.
    http.event.accountName=<global_account_name of the format customer1_74678b04-8a71-40ef-acaf-9adb05eeb815>
    # Replace this value with the access key of the account name configured above.
    http.event.accessKey=<a_long_key_value such as SJ5b2m7d1$354>

    The account name is the global account name of the account available on the View License UI of the Controller. The access key provides an authentication mechanism between the Controller and the components of the Application Analytics deployment. The Controller installation process generated the accessKey value. It is also available on the License screen in the Controller.  The following screenshot shows you the License UI where you can find the appropriate values.

  6. If collecting log information on this host, configure log analytics using one or more of the pipeline templates. For details, see Configuring Log Analytics.

  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 new 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 the Analytics Agent (.NET)

For .NET installations, you install the separate Analytics Agent, which is written in Java. As described in Deployment Options and Scenarios, the Analytics Agent can run on the same host or on a  different host from the monitored applications, depending on your use case. This procedure installs the Analytics Agent as a Windows service.

If you are running the Standalone Machine Agent on the same machine as your .NET app agent, it is not necessary to install a separate Analytics Agent. See To enable the Analytics Agent (.NET) Using Standalone Machine Agent.


To enable the Analytics Agent for .NET

The Windows installer that installs the Analytics Agent as a service is new in 4.1.2

  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 scripts for Windows(.bat) and 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. On each host where the Standalone Machine Agent is deployed and you want to enable the Analytics Agent,  use a text editor to open /analytics-agent/monitor.xml and set the enabled tag to true as shown here. 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>
    ...
  3. 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
  4. If collecting log information on this host, configure log analytics. For details, see Configuring Log Analytics.

  5. Save and close the file.

  6. Run the following command to install the Analytics Agent as a service.

    bin\analytics-agent.bat install-analytics-agent

    Now your analytics-agent can be managed like any other windows service. 

  7. 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 app 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-premise installations, in clustered environments, often a load balancer. If your firewall rules use IP addresses, review the Section "Firewall Considerations" in this topic: Troubleshooting.

  3. Configure the account and account key where the agent should publish data as the accountName and accessKey values. For example: 

    # The account in the Controller for this analytics data.
    http.event.accountName=<global_account_name of the format customer1_74678b04-8a71-40ef-acaf-9adb05eeb815>
    # Replace this value with the access key of the account name configured above.
    http.event.accessKey=<a_long_key_value such as SJ5b2m7d1$354>

    The account name is the global account name of the account available on the View License UI of the Controller. The access key provides an authentication mechanism between the Controller and the various components of the Application Analytics deployment.  The accessKey value is generated during the Controller installation process and is also available on the View License UI of the Controller.

  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
      Note the .NET 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

To enable the Analytics Agent (.NET) Using Standalone Machine Agent

In the case where you are running both the .NET App 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 app 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 collecting log information on this host, configure log analytics. For details, see Configuring Log Analytics.

  6. Restart the Machine Agent.

To Start and Stop the Analytics Agent (.NET)

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 start-service

    (info) If you need to change any JVM start-up options, use a text editor to modify <analytics-agent-home>\conf\analytics-agent.vmoptions

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

    bin\analytics-agent stop-service

To Uninstall the Windows Service

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

bin\analytics-agent.bat uninstall-analytics-agent

Troubleshooting Tips

  • Make sure that the properties in analytics-agent.properties are properly set.
  • 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"

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.

  1. In the Controller UI, select the Analytics tab. 
  2. Select Configuration.
  3. Select the Application you wish to monitor from the dropdown menu.
  4. Check Enable.

Configuring the Analytics Agent on a Different Host

The default settings assume that the Analytics Agent is on the same host and uses the same default port as your App 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/v1/sinks/bt
Replace <analytics-agent-ip> with the hostname of the Analytics Agent for your environment.  

For .NET

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

  • Add a system environment variable named "appdynamics.analytics.agent.url" and set the value to http://<analytics-agent-ip>:9090/v1/sinks/bt. Replace <analytics-agent-ip> with the hostname of the Analytics Agent for your environment. Reboot the machine to ensure that this takes effect.
  • 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 which is invoking the monitored process must have the env var set. To ensure this, the easiest procedure is to restart the machine.

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

Add a new environment variable as shown:


Connect the Agent to the Events Service through a Proxy (Optional)

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

    1. Java: Open <machine-agent-home>\monitors\analytics-agent\conf\analytics-agent.properties with a text editor.  
      .NET: 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>