AppDynamics Extensions Troubleshooting Guide
Before proceeding with this document, go through the Extensions Prerequisites Guide and verify whether the environment and agents being used have been set up correctly.
Contents
- Downloading & Placing an Extension
- Configuring an Extension
- Restarting the Machine Agent
- Locating your Custom Metrics
- Metric Limits
- Contacting Support
1. Downloading and Placing an Extension
Ensure that the correct extension has been downloaded from the AppDynamics Exchange and extracted to the <MachineAgentHome>/monitors directory. It is important to verify the supported Controller, Machine Agent & artifact versions from the Extension's documentation.
2. Configuring an Extension
Every monitoring extension is shipped with a file called config.yml. The following steps must be verified for the config.yml:
2.1. Metric Prefix
Most config.yml files contain two metricPrefix sections which may look like the following:
(Considering the Redis Monitoring Extension as an example)
2.1.1. metricPrefix: "Custom Metrics|Redis"
This metric prefix is recommended when SIM is enabled.
2.1.2. metricPrefix: "Server|Component:<COMPONENT_ID>|Custom Metrics|Redis"
This metric prefix is recommended when one or more app agents coexist on the same host with the MA. Check APM Machine Agent Installation.
This metric prefix points to one specific component (tier). The COMPONENT_ID can be found by using these steps:
1. Go to your Controller
2. Select the Application associated with your Machine Agent.
3. Select “Tiers and Nodes” and select the exact tier corresponding to your Machine Agent.
4. Once you select the Tier, click the Details button to open the Dashboard.
5. Once you reach the Dashboard, take a look at the URL and find the word component and the value corresponding to it.
6. That value should be a number and that is your tier ID or component ID that you need to update as your Component_ID value in the config.
Note: The component ID or component name here is the same as the tier ID or tier name. To get the component ID, please check the URL as specified here:
IMPORTANT: The component ID or component name specified in the metric prefix of the extension should match the corresponding tier of the Machine Agent. The extension cannot report to a tier different than its Machine Agent's tier.
To maintain the brevity of this document, advanced metric prefix configuration scenarios are not discussed in this article. Please refer Advanced metric prefix configuration scenarios for extensions.
2.2 Formatting
After verifying the metric prefix and configuring the details of the artifact monitored by the extension, ensure that the config.yml is correctly formatted. The use of Tabs is not supported by YML files. The file can be validated using an online YML validator like http://www.yamllint.com/
2.3. Monitor.xml
Another file present in the extracted extension's directory is the monitor.xml. In most cases, this file does not need any changes. Please disregard the following unless the monitor.xml has to be modified:
2.3.1 Execution frequency
An extension ships with a default execution frequency of 60 seconds. The highest execution frequency supported by monitoring extensions is 5 minutes (300 seconds). It is important to ensure that this limit is not exceeded, as it will lead to inconsistencies in metric values.
2.3.2 Path to config.yml
Ensure that the path to the config.yml is correctly specified under the following tag:
<task-arguments>
<argument name="config-file" is-required="true"
default-value="monitors/RedisMonitor/config.yml" />
</task-arguments>
An absolute path can also be used here.
3. Restarting the Machine Agent
At this point, ensure that the Machine Agent has been restarted. Deploying new extensions and making changes to the monitor.xml for previously deployed extensions require a Machine Agent restart. However, simply changing the contents of a previously deployed extension's config.yml does not require a Machine Agent restart.
4. Where do I look for Custom Metrics?
Once everything has been configured correctly, follow these steps to look for Custom Metrics in the Controller:
4.1. SIM
- If SIM is enabled, navigate to the Servers tab in the main menu bar.
- Click on Metric Browser at the bottom-left. A new window should open up.
- Expand the 'Root' server, or alternatively, the server configured under the 'Machine Path' section of the
<MachineAgentHome>/conf/controller-info.xml. - Select Custom Metrics. Metrics from the configured extensions should show up here, in their respective directories.
4.2. Standalone Machine Agent (SIM disabled)
- Find the Application associated with the Machine Agent under the Applications tab in the main menu bar.
- Click on Metric Browser at the bottom-left. A new window should open up.
- Select Application Infrastructure Performance, and look for the Tier associated with the Machine Agent
- Under this tier, look for Custom Metrics. Metrics from the configured extensions should show up here, in their respective directories.
- The data in the previous point is a tier-level value, an aggregation of data represented by each node under this tier. To get metrics pertaining to a specific node, the Individual Nodes section must be used.
5. Metric Limits
If all the steps to this point have been followed, but all the required metrics are still not seen in the Metric Browser, it could be a case of the Machine Agent's metric limit being hit, and it should be restarted with a higher metric limit. For example, to increase the limit to 5000, the following command can be used while starting the Machine Agent:
java -Dappdynamics.agent.maxMetrics=5000 -jar machineagent.jar
However, note that this limit should not be an arbitrarily large number. It is a factor of the number of metrics generated by any installed extensions, heap memory provided to the Machine Agent, etc. Check the hardware and sizing requirements for Machine Agents and extensions in the Standalone Machine Agent Requirements and Supported Environments document.
More information, see the latest Metric Limits document.
At this point, if the extension’s metrics are still not visible, please refer to the extension-specific troubleshooting steps (if any) found on the respective extension documentation pages.
6. Contact the Support Team
Open a ticket with AppDynamics Support if the required metrics still aren’t visible in the Controller. It is imperative to attach the config.yml, monitor.xml, controller-info.xml and 10-15 minutes of Machine Agent DEBUG logs to the ticket.
To enable DEBUG logs in the Machine Agent:
1. In <MachineAgentHome>/conf/logging/log4j.xml, change the level values of the following <logger> elements from INFO to DEBUG:
<logger name="com.singularity">
<logger name="com.appdynamics">
2. Let the Machine Agent run for 10-15 minutes and attach the entire <MachineAgent>/logs/* directory to the ticket.
