In all AppDynamics Application Analytics deployment scenarios, 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.
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:
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.
JVM Options
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:
On the host running the Standalone Machine Agent, use a text editor to open
<machine-agent-home>/monitors/analytics-agent/monitor.xml.
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> ...
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
In the
analytics-agent.properties
file, change the default URL and, if necessary, the port number for connecting to the Events Service by modifying thehttp.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.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. Thehttp.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: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, 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 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.
If you are running the Standalone Machine Agent on the same machine as a .NET 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
- 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
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
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 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.
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).
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.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. Thehttp.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: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
(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:
- Confirm that you are running the Standalone Machine Agent and the .NET Agent, on the same machine.
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> ...
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
- Save and close the file.
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.
To start the agent service from the command line:
bin\analytics-agent.exe service-start
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"
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.
- 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>.
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.
- Edit the properties file as follows:
- Java: Open
<machine-agent-home>\monitors\analytics-agent\conf\analytics-agent.properties
with a text editor. - Windows: Open
<analytics-agent-home>\conf\analytics-agent.properties
with a text editor.
- Java: Open
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.