Troubleshoot Analytics Issues

General Troubleshooting Issues

If you encounter problems with your Analytics deployment, check the logs for errors and warnings.

These logs are useful to:

• Determine if the Analytics Dynamic Service is enabled or disabled. 
• Determine if the Analytics Dynamic Service encounters errors sending messages to the Analytics Agent. For example, when the Analytics Dynamic Service is not able to communicate with the Analytics Agent due to invalid connection configuration.
• Determine if messages are being dropped by the Analytics Dynamic Service because its internal buffers are full.
• View the configurations used on startup.

The following components write log information.

• Analytics Agent: The Analytics Agent writes log messages to files in the <analytics_agent_home>/logs directory. 
• Events Service: The Events Service writes log messages to files in the <events_service_home>/logs directory. The events-service-api-store.log file can help with troubleshooting. 
• Java Agent: The Analytics Dynamic Service is built into the Java Agent and writes logs to the same file as the app agent. The logs are in the <application_home>/<app_agent_home>/logs directory. 
  • The primary log file to use for troubleshooting is the file named agent.<timestamp>.log. Search the file for messages written by the Analytics Dynamic Service. 
• .NET Agent: The .NET Agent writes log messages to files in the  %ProgramData%\AppDynamics\DotNetAgent\Logs directory. By default, the .NET Agent writes Analytics logs from the com.appdynamics.ee.service.analytics.Analytics logger to determine if the Analytics Dynamic Service is enabled/disabled and to view the configuration on startup. Errors are logged in the warnfile.
  • The com.appdynamics.CONFIG.AnalyticsDynamicServiceConfigListener logger gathers Analytics Dynamic Service configuration details from the Controller. Ensure that the eventServiceURL comes from the Controller.
  • The com.appdynamics.analytics.EventsServiceSink logger provides information about the communication between the .NET Agent and the Events Service. 
    
  For additional logger information, see .NET Agent on Windows Logging.

Configuration Issues

Verify that your configuration settings are properly configured with the required account name and key. Slashes in account names and key values must be escaped.

Starting the Analytics Agent Issues

If an instance of the Analytics Agent terminates and leaves behind a process ID file (PID file), the next agent startup will fail with the following error:

java.lang.RuntimeException: Unable to create file [D:\AppDynamics\analytics-agent\analytics-agent.id] to store the process id because it already exists. Please stop any currently running process and delete the process id file

In agent versions prior to 4.3, you needed to delete the old process id file and restart the agent to work around this issue.

For versions 4.3 and later, you can use the -f flag option while starting the agent. This option causes a pre-existing process id file to be deleted. The flag is not required when you are starting the agent as a Windows service. 

Use the -f flag as follows:

• UNIX type OS: start -f
• Windows CLI: start -f

The -f flag option only works for the standalone Analytics Agent. This option does not work for the Analytics Agent embedded in the Machine Agent. In versions 20.6 and later of the Machine Agent, the bundled Analytics Agent no longer drops a PID file.

For the Analytics Agent running inside the Machine Agent (embedded mode), upgrade the Machine Agent to 20.6. You no longer need to delete PID files from previous runs where the agent crashed.

Transaction Analytics Without an Analytics Agent (Agentless Analytics) Issues

This section describes known issues with Agentless Analytics. 

Known Issues

• On Windows, you cannot delete a log file with the del command while the analytics agent is collecting log data from the file.
• To prevent high CPU usage, AppDynamics recommends the Java Agent version 20.3 and later (or 4.5.19 if necessary). 
• Look out for high CPU and memory usage in the .NET Agent.
• Avoid using robocopy/move commands to move files in Windows. Instead, AppDynamics recommends that you use the move command.
• If you are running the Analytics Agent as an extension to the Machine Agent with JRE 1.8.0_171 or later, starting the Analytics Agent with encrypted credentials will fail. Disable encryption or use JRE 1.8.0_162 to run the Machine Agent.

Enable Transaction Analytics Without an Analytics Agent on .NET Applications

You can enable Agentless Transaction Analytics at the Controller, node/tier, and agent level. 

By default, Agentless Analytics is disabled for the .NET Agent. Enabling Agentless Analytics changes your deployment to Agentless Analytics mode. 

Enable on the Controller

To enable Agentless Analytics at the Controller level: 

1. Navigate to http://<localhost:port>/controller/private/ControllerFlagsServlet.
2. Set appdynamics.analytics.features.agentless.enabled to true.
3. The .NET Agent automatically picks up the configuration.

To disable the feature across the Controller, pass the property to the domain.xml file, as shown below.

<jvm-options>-Dappdynamics.analytics.features.agentless.enabled=true</jvm-options>

Enable Agentless Analytics on Particular Tiers or Nodes

To enable the feature at the tier or node level, add the agentless-analytics-disabled property and set to false. When set to false, this node property changes the tier/node to Agentless Analytics mode. To add a node property, see App Agent Node Properties. 

Disable Agentless Analytics

To disable Agentless Analytics, remove the properties referenced above or set the value of agentless-analytics-disabled to true.

Existing Analytics Agents

Once you upgrade to the minimum Controller and agent versions, existing Analytics Agents stops reporting data. Agentless Analytics does not duplicate data from the Analytics Agent. AppDynamics recommends that when you see Transaction Analytics in the Controller, you can uninstall the Analytics Agent unless you are using Log Analytics.

Disable Transaction Analytics Without an Analytics Agent on Java Applications

You can disable Agentless Transaction Analytics at the Controller, node/tier, and agent level. 

By default, Agentless Analytics is enabled for the Java Agent. Disabling Agentless Analytics reverts your deployment back to Analytics Agent mode. 

Disable on the Controller

To disable Agentless Analytics at the Controller level: 

1. Navigate to http://<localhost:port>/controller/private/ControllerFlagsServlet.
2. Set appdynamics.analytics.features.agentless.enabled to false.
3. Restart the Java Agent or refresh the configuration in your Controller.

To disable the feature across the Controller, pass the property to the domain.xml file, as shown below.

<jvm-options>-Dappdynamics.analytics.features.agentless.enabled=false</jvm-options>

Disable Agentless Analytics on Particular Tiers or Nodes

To disable the feature at the tier or node level, add the agentless-analytics-disabled property and set to true. When set to true, this node property reverts the tier/node to Analytics Agent mode. To add a node property, see App Agent Node Properties. 

Re-Enable Agentless Analytics

To re-enable Agentless Analytics, remove the properties referenced above or set the value of agentless-analytics-disabled to false.

For the Java Agent, you need to manually disable and re-enable Transaction Analytics for your Java applications.

1. In the Controller UI, navigate to Analytics > Configuration. 
2. Go to the Transaction Analytics - Configuration tab, and find the desired application. 
3. Uncheck the app(s). Wait a few minutes for processing. 
4. Recheck the app(s) and select your business transaction(s). Wait a few minutes for the agents to receive information.

Existing Analytics Agents

Once you upgrade to the minimum Controller and agent versions, existing Analytics Agents stops reporting data. Agentless Analytics does not duplicate data from the Analytics Agent. AppDynamics recommends that when you see Transaction Analytics in the Controller, you can uninstall the Analytics Agent unless you are using Log Analytics.

Analytics Data Issues

Clock Management

AppDynamics recommends maintaining clock-time consistency throughout your monitored environment. If Analytics metrics are consistently reporting zero, confirm that clocks are synchronized across the application, Controller, and Events Service nodes. 

Timestamps

There are potentially four time zones involved with Log Analytics:

1. The timestamp and time zone from the log file.
2. The event timestamp and pickup timestamp time zones can be different from those in the log for a number of reasons:
   1.  When the time zone is overridden.
   2. The time zone is not provided correctly in the log.
   3. The timestamp and time zone parsing goes awry.
   4. When no time zone is specified in the log timestamp, then local time is assumed.
3. The Events Service time zone and the Events Service stores all timestamps in UTC time.
4. The browser used to view the Analytics data in the Controller UI (such as the Event Timestamp column in the UI search results or the Time Picker widget) converts all timestamps to the browser's local time.

Environment Variables

If you are not seeing or only seeing partial Analytics data in the Controller, configure the following environment variables.

Log Analytics Missing Field Extractions Issues

If you are missing fields in your Log Analytics data that you expect to see based on your source rule configuration or using regex (including grok patterns) in your field extraction, you may encounter a performance safeguard.

If a regex pattern takes more than five seconds to match against a log line, the attempt to extract the fields is terminated. No further processing that requires the extracted fields will occur. As a result, some fields may be missing when viewed on the Controller for that log line. In this case, the following error message appears in the Analytics Agent log: 

[ERROR ] java.util.concurrent.TimeoutException: The current regex has spent 5 seconds attempting to match the log line, further processing has been stopped for this log line.

Another reason for missing fields is if the log line doesn't contain the field to be extracted as defined in the pattern. 

Custom Analytics Metrics Issues

If you are having issues with metrics created from saved searches or with the alerts performance for those metrics, try increasing the query batch size. You can increase the size using the analytics.scheduledqueries.batch.size Controller setting in Controller Settings > Controller Configurations. The default value for this setting is 5. 

See Access the Administration Console for information about accessing the setting.  

Business Transaction Events Limits

The Analytics Dynamic Service sends messages to the Events Service where the request body is an array of event segments. A business transaction event consists of one or more segments that are related to each other by the business transaction requestGUID. There are ingestion limits related to messages.

• Event (segment) size: The maximum size of an individual business transaction segment collected by the Analytics Dynamic Service is .1 MB. This limit is defined by the appdynamics.analytics.message.maxSizeBytes Java system property. To change this value, pass it on the command line as a system property when the Java Agent starts. For example:

  '-Dappdynamics.analytics.message.maxSizeBytes=1024000'

  CODE

• Events per request: The maximum number of segments per request is defined by the appdynamics.analytics.agent.send.batch.items.max Java system property. The default value of this property is 16. To change this value, pass it on the command line as a system property when the Java Agent is started.  

• Message Size: This limit refers to the size of a single request body sent to the Events Service, which is usually an array of event segments. Publish requests for all event types are limited to 1 MB. If the limit is exceeded, you will see exceptions in agent log file and messages in Events Service logs. 

Firewall Considerations

Transaction Analytics without an Analytics Agent requires a connection between the Java/.NET Agent and the Events Service. If you have a firewall that blocks requests from the Java/.NET Agent to the SaaS or on-premises Events Service, you need to open the firewall to avoid gaps in Analytics data. See Connection Ports and Agent-to-Controller Connections.

For SaaS-based installations, configure the Analytics endpoint by modifying the http.event.endpoint setting in the \conf\analytics-agent.properties file (as described in Install Agent-Side Components). For example, http.event.endpoint=http://analytics.api.appdynamics.com:443. 

If your firewall rules require you to use specific IP addresses, rather than hostnames, note the following information. If you are unable to see Transaction Analytics data collected as expected (even after configuring your firewall rules) and you see repetitive Connection Reset messages in the logs similar to the following, your firewall rules may not include the correct IP addresses.

[2015-12-18T16:08:39,907-06:00] [INFO ] [AD Thread Pool-Global0] [o.a.http.impl.execchain.RetryExec] I/O exception (java.net.SocketException) caught when processing request to {s}->https://analytics.api.appdynamics.com:443: Connection reset

Your firewall rules may not include the correct IP addresses.

In SaaS environments, analytics.api.appdynamics.com, fra-ana-api.saas.appdynamics.com, and syd-ana-api.saas.appdynamics.com are round-robin DNS aliases and may resolve to multiple DNS (54. vs 52.) in the following examples.

Name: analytics.api.appdynamics.com
Address: 54.213.173.141
Name: analytics.api.appdynamics.com
Address: 52.88.111.157

Name: fra-p-con-2.saas.appdynamics.com
Address: 52.28.42.67
Name: fra-p-con-2.saas.appdynamics.com
Address: 52.57.96.225

Name: syd-p-con-1.saas.appdynamics.com
Address: 54.153.248.179
Name: syd-p-con-1.saas.appdynamics.com
Address: 54.153.246.219

Amazon Web Services (AWS) controls the IPs used, so they may change from time to time. AWS publishes its current IP address ranges in JSON format, so if you are unable to open firewalls to hostnames, you can download the AWS IP address ranges. If you want to be notified whenever there is a change to the AWS IP address ranges, you can subscribe to receive notifications using Amazon SNS. 

See Analytics IP Ranges for the AWS regions for the SaaS Analytics environments. You can view the AWS IP Ranges for each listed region.