AppDynamics Application Intelligence Platform

3.8.x Documentation

PDFs

Videos

Release Notes

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:
APPLICATION, APPLICATION_COMPONENT, APPLICATION_COMPONENT_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:
http://<controller-host-url>/#location=APP_INCIDENT_DETAIL&incident=
Append the incident ID to the URL to provide a link to the Controller UI for this policy violation

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=
Append each event summary ID to the URL to provide a link to the Controller UI for this event

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

3 Comments

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

     

     

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

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