AppDynamics Application Intelligence Platform
3.8.x Documentation
If you are using an on-premise controller, you can set up a custom action on the controller instance to integrate notification of AppDynamics health rule violations and events with an alerting or ticketing system. Use a push approach by creating custom notifications that pass the information to your alerting system.
Custom Notifications and Custom Actions
A custom notification lets you integrate alerts about AppDynamics health rule violations and events into your own alerting system. This integration extension requires:
- An on-premise controller
- A custom.xml file that provides information about the custom notification
- An executable script that accepts parameters from AppDynamics about the events and health rule violations that trigger an alert
- Configuring AppDynamics events or policies to trigger the custom notification via a custom action
Creating a Custom Action
To create a custom action script
1. At the top level of the Controller installation directory, create a directory named "custom" with a sub-directory named "actions".
<controller_install_dir>/custom/actions
2. In the <controller_install_dir>/custom/actions directory, create a subdirectory for each custom action script that you will install. For example,
<controller_install_dir>/custom/actions/jira
for an action that interfaces with a JIRA system.
3. For each custom action that you want to implement, create an executable script (.bat extension for Windows, .sh extension for Linux) that can accept and process the parameters passed to it by AppDynamics. See Information Passed to the Custom Action Script from AppDynamics for details on the parameters.
Create this script in the appropriate subdirectory that you created in step 2.
Set correct executable permissions for the shell scripts in a Linux environment. For example: chmod 770 script1.sh.
Ensure that the script file has the correct character encoding. This is especially important when creating a Unix shell script on a Windows machine.
4. In the <controller_install_dir>/custom/actions directory, create a custom.xml file that describes the location and name of your custom action script(s).
See Contents of the custom.xml File.
5. After you have installed the script(s) and the custom.xml file, restart the Controller.
6. Verify the script manually.
To verify the script:
a. Open a command-line console on the Controller host machine.
b. Execute the script file from the command line console.
7. Create the custom action in the AppDynamics UI. See Custom Actions.
Contents of the custom.xml File
The custom.xml file has an <actions> element for every custom action on the controller.
The <type> element contains the subdirectory that contains the script file.
The <executable> element contains the name of the script.
Sample custom.xml file
<custom-actions>
<action>
<type>jira</type>
<executable>script1.bat</executable>
</action>
<action>
<type>bugzilla</type>
<executable>script2.sh</executable>
</action>
</custom-actions>
Information Passed to the Custom Action Script from AppDynamics
The custom action script must handle the parameters passed to it from a health rule violation event or any other type of event.
Parameters passed by a health rule violation
For a health rule violation, the custom action script is invoked with the following string parameters:
Health Rule Violation Parameter | Repeated Parameter | Notes |
|---|---|---|
APP_NAME | none | name of the business application |
APP_ID | none | application ID number |
PVN_ALERT_TIME | none | alert time, such as: Thu Dec 22 15:03:56 PST 2011 |
PRIORITY | none | priority number |
SEVERITY | none | allowed values: INFO, WARN, or ERROR (In the AppDynamics UI they are called "Info", "Warning", and "Critical") |
TAG | none | or the empty string if no tag was specified by the user |
HEALTH_RULE_NAME | none | name of the health rule that was violated |
HEALTH_RULE_ ID | none | health rule ID number |
PVN_TIME_PERIOD_IN_MINUTES | none | health rule violation time period in minutes |
AFFECTED_ENTITY_TYPE | none | allowed types: APPLICATION, APPLICATION_COMPONENT (aka Tier), APPLICATION_COMPONENT_NODE, BUSINESS_TRANSACTION, APPLICATION_DIAGNOSTIC_DATA (aka Error) |
AFFECTED_ENTITY_NAME | none | the affected entity name |
AFFECTED_ENTITY_ID | none | the affected entity id |
NUMBER_OF_EVALUATION_ENTITIES | none | number of entities (BT, App, Tiers, Nodes, Errors, JMX counters, etc..) violating health rule conditions |
EVALUATION_ENTITY_TYPE | Yes, one for each evaluation entity | allowed types: APPLICATION, APPLICATION_COMPONENT (aka Tier), APPLICATION_COMPONENT_NODE, BUSINESS_TRANSACTION, APPLICATION_DIAGNOSTIC_DATA (aka Error), JMX |
EVALUATION_ENTITY_NAME | Yes, one for each evaluation entity | the evaluation entity name (for JMX it is the counter name) |
EVALUATION_ENTITY_ID | Yes, one for each evaluation entity | the evaluation entity id or <NULL> for JMX |
NUMBER_OF_TRIGGERED_CONDITIONS_PER_EVALUATION_ENTITY | Yes, one for each evaluation entity | number of times to loop through the triggered condition parameters for each evaluation entity |
triggered condition | Yes, listed below | if more than one condition is triggered, the parameters repeat for each triggered condition, where "x" increments the number representing the condition |
| SCOPE_TYPE_x | the scope of the parameter, whether the scope is the application, tier, or node: |
| SCOPE_NAME_x | the name of the scope, such as: ACME Book Store Application |
| SCOPE_ID_x | the scope id |
| CONDITION_NAME_x | the health rule condition name |
| CONDITION_ID_x | the health rule condition id |
| OPERATOR_x | allowed operators: LESS_THAN, LESS_THAN_EQUALS, GREATER_THAN, GREATER_THAN_EQUALS, EQUALS, NOT_EQUALS. |
| CONDITION_UNIT_TYPE_x | the condition for the threshold parameter: ABSOLUTE, BASELINE_STANDARD_DEVIATION, BASELINE_PERCENTAGE, BASELINE_PERCENTILE |
| USE_DEFAULT_BASELINE_x | a Boolean parameter (true or false) applicable only when the condition unit type is one of the BASELINE_ types |
| BASELINE_NAME_x | applicable only when the condition unit type is one of the BASELINE_ types and the use default baseline parameter is "false" |
| BASELINE_ID_x | applicable only when the condition unit type is one of the BASELINE_ types and the use default baseline parameter is "false" |
| THRESHOLD_VALUE_x | health rule threshold setting |
| OBSERVED_VALUE_x | value that violated the health rule threshold |
SUMMARY_MESSAGE | none | summary of the notification, such as: "Health rules have been violated." |
INCIDENT_ID | none | the incident identifier number for this health rule violation |
DEEP_LINK_URL | none | controller deep link URL, such as: |
EVENT_TYPE | none | POLICY_OPEN_WARNING,POLICY_OPEN_CRITICAL, POLICY_CLOSE, POLICY_OPEN_UPGRADED, POLICY_OPEN_DOWNGRADED |
Parameters passed for an event that is not a health rule violation event
For an event that is not a health rule violation event, the custom action script is invoked with the following string parameters:
Event Notification Parameter | Repeated Parameter | Notes |
|---|---|---|
APP_NAME | none | name of the business application |
APP_ID | none | application ID number |
EN_TIME | none | event notification time, for example: Wed Jan 04 09:36:55 PST 2012 |
PRIORITY | none | priority number |
SEVERITY | none | Allowed values: INFO, WARN, or ERROR (In the AppDynamics UI they are called "Info", "Warning", and "Critical") |
TAG | none | or <NULL> if it was not specified by the user |
EN_NAME | none | name of the event notification |
EN_ID | none | event notification ID number |
EN_INTERVAL_IN_MINUTES | none | event notification interval in minutes |
NUMBER_OF_EVENT_TYPES | none | determines how many times to loop through the event type map parameters |
event type | yes, listed below | if there is more than one event type, the parameters repeat for each event type, where "x" increments the number representing the event type |
| EVENT_TYPE_x | type of event, such as: ERROR, APPLICATION_ERROR, APPLICATION_INFO, STALL, BT_SLA_VIOLATION, DEADLOCK, MEMORY_LEAK, MEMORY_LEAK_DIAGNOSTICS, LOW_HEAP_MEMORY, ALERT, CUSTOM, APP_SERVER_RESTART, BT_SLOW, SYSTEM_LOG, INFO_INSTRUMENTATION_VISIBILITY, AGENT_EVENT, INFO_BT_SNAPSHOT, AGENT_STATUS, SERIES_SLOW, SERIES_ERROR, ACTIVITY_TRACE, OBJECT_CONTENT_SUMMARY, DIAGNOSTIC_SESSION, HIGH_END_TO_END_LATENCY, APPLICATION_CONFIG_CHANGE, APPLICATION_DEPLOYMENT, AGENT_DIAGNOSTICS, MEMORY, LICENSE |
| EVENT_TYPE_NUM_x | number of events of this type |
NUMBER_OF_EVENT_SUMMARIES | none | number of event summaries in the notification; determines how many times to loop through the event summary parameters |
event summary | yes, listed below | if there is more than one event summary, the following parameters repeat for each event summary, where "x" increments the number representing the event summary |
| EVENT_SUMMARY_ID_x | event summary ID number |
| EVENT_SUMMARY_TIME_x | event summary time, for example: Wed Jan 04 09:34:13 PST 2012 |
| EVENT_SUMMARY_TYPE_x | type of event, such as: APPLICATION_CONFIG_CHANGE, APP_SERVER_RESTART, DIAGNOSTIC_SESSION, STALL |
| EVENT_SUMMARY_SEVERITY_x | event severity, such as: INFO, WARN, or ERROR (In the AppDynamics UI they are called "Info", "Warning", and "Critical") |
| EVENT_SUMMARY_STRING_x | event summary string, such as: Application Server environment variables changed |
DEEP_LINK_URL | none | http://<controller-host-url>/#location=APP_EVENT_VIEWER_MODAL&eventSummary= |
The current custom action implementation will most likely pass more than nine parameters to the executing script.
In Windows and Linux environments, more than nine command line parameters can be processed only if the SHIFT command is used.
For more information, see Command Line parameters.
Sample Alerting Extension
You can download an alerting extension that interfaces with the PagerDuty alerting and incident tracing system.
Learn More
Overview
Content Tools
Apps
3 Comments
Unknown User (tdepuy@xmatters.com)
I'm guessing these parameters are passed sequentially on the command line? I.e.
script1.sh APP_NAME APP_ID PVN_ALERT_TIME ...
Unknown User (tdepuy@xmatters.com)
For step 6.a. can you provide a command that would simulate what AppDynamics would send?
I.e:
myscript.sh parm1 parm2 parm3
Where parm1, parm2, and parm3 are APP_NAME, APP_ID, PVN_ALERT_TIME etc? Something that we could copy and paste to run our script to get valid input.
Steve Hetland
Hi Travis, Sorry for a delayed reply to your earlier comment. Yes, the arguments are passed sequentially, but as arguments to your custom action script.
I will update the doc with more details, but for now have a look at some of our samples. Here's where the Splunk alerting extension capture the arguments to the custom action:
https://github.com/Appdynamics/splunk-alerting-extension/blob/master/src/main/java/com/appdynamics/splunk/splunkClient/SendADNotificationToSplunk.java
You can see the point-of-the-view of the invoker (AppDynamics) from the test script for the extension, here:
https://github.com/Appdynamics/splunk-alerting-extension/blob/master/src/main/custom/actions/notify-splunk-of-policy-violation/test_notify-splunk-of-policy-violation.sh
Feel free to browse around the AppDynamics repositories on GitHub. There are many other examples there you can use as a starting point for your custom extension. However, note that some of the extensions were written to an older version of the product, and may not reflect the latest. Take a look at the readme.md file and recent activity for the repo to get an idea about this.
Thanks,
Steve