PDFs


This page applies to an earlier version of the AppDynamics App IQ Platform.
See the latest version of the documentation.


Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 23 Current »

On this page:

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. Select the components you need based on your requirements. 

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 or the Analytics Agent standalone binary deployed.
  • To collect log and transaction data, the machine must have either a Standalone Machine Agent or the Analytics Agent standalone binary deployed 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 app server agents in your environment. To access the Analytics functionality, the app server agent must be version 4.0 or later. See Instrument Java Applications and Instrument .NET Applications for more information.  

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.

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, 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 will need to uninstall the service and reinstall it for the changes to take effect.

Enable the 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 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.  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 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 your log sources. 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 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 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 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. 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.

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 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, configure your log sources. For details, see Configuring Log Analytics.

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

    • 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
To enable the Analytics Agent using Standalone Machine Agent

In the case where you are running both the .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 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 (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

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"

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.

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. Select the Application you wish to monitor from the dropdown menu.
  4. Check Enable.

Configuring 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 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 an 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 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>
  • No labels