/alarms

You can use the Pepperdata REST API to access Pepperdata resources. For example, if you have a job that runs for a long time, in the job’s launch script or program, you can programmatically create an alarm that fires only for this job. This method is a good alternative when you cannot use the dashboard to directly create an alarm because the job in question is no longer running, and therefore its job Id is no longer valid.

To create, retrieve, or delete alarms for your cluster (realm), access the /alarms endpoint by any of the following methods:

• cURL command line tool
• web browser (we recommend using a JSON prettifier plugin for your browser)
• programmatically

The table describes the API resources, which are the same regardless of your access method.

* For the alarm fields that should remain unchanged, be sure to exactly match the data fields in your request to the alarm’s existing values, and change only those fields that you want to be changed. If you omit a field, it will be overwritten with its default, as described in Data Format of the Alarms API, below.

Data Format of the Alarms API

The Pepperdata REST API alarms resource returns an array of alarm objects, each defined as follows. Unless noted otherwise, all fields are required. Do not specify read-only fields; they are ignored.

• id: (Read-only) Pepperdata-assigned unique number for the alarm.

• title: User-specified alphanumeric string to describe the alarm.

• enabled: (Optional; default=enabled) Alarm enabled/disabled flag. To enable the alarm, omit or specify “true”; to disable the alarm, specify “false”.

• queryParams: Dashboard query for the alarm’s metrics. In general, the easiest way to determine the correct query is to model it on an existing alarm that is very similar to the alarm that you want to create. If the metrics chart contains multiple time series, each time series is individually evaluated. Alarms are fired any time any of the series crosses the alarm threshold.

• threshold: Object that contains the alarm firing criteria.

  • value: Floating point number above/below (as specified by the extremumOperator value) which the alarm will fire.

  • windowMinutes: (Optional; default=5) Positive integer of the duration (in minutes) to which to apply the percentOfTime trigger value.

  • percentOfTime: (Optional; default=1) Percentage of time (integer from 0–100) in the windowMinutes duration in which the metric must be be above/below the threshold value before the alarm fires. (Behavior is undefined for integers outside the expected 0–100 range.)

  • extremumOperator: (Optional; default=MAX/upper). Upper/lower threshold. To set an upper threshold, above which the alarm will fire, specify “MAX”. To specify a lower threshold, below which the alarm will fire, specify “MIN”.

• createdTime: (Read-only) Time the alarm was created.

• updatedTime: (Read-only) Time the alarm was most recently updated.

• targetEmails: (Optional) Comma-separated list of email override addresses to receive alert notifications (email messages) every time the alarm fires and clears.

  Email override addresses override the default Alert Connections email addresses. That is, for alarms with email overrides, the email alerts are sent to the override addresses but not to the default email addresses. PagerDuty alerts are unaffected, and Pepperdata continues to send alerts to PagerDuty for all alarms.

• shouldFailOnMissingSeries: For internal use only.

• createdByEmail: (Read-only) Email address of the user who created the alarm. Blank for legacy alarms—alarms created before mid-March, 2018.

• thresholdQueryParams: (Read-only) Threshold-related information required by Pepperdata to draw the threshold line on related metrics charts.

• predefinedAlarm: (Read-only) Flag to indicate whether the alarm is predefined—a default Pepperdata alarm for basic system resource usage, which you can disable or customize, but cannot delete.

Use cURL to Access the Alarms API

The procedure shows a minimal example using cURL requests to demonstrate the basic syntax and methods.

Prerequisites

Before you can use cURL to retrieve alarms, you must generate an API key.

Navigate to the API Keys page on the Pepperdata dashboard account management page, and click Create API key. Be sure to copy both the key id (<API-key-id>) and, especially, the token (<API-key-token>), which cannot be retrieved after you navigate away from the API Keys page. Pepperdata persists the key, and you can use it until you delete it.

Procedures

You can perform the following procedures in any order.

• Create an Alarm

  1. Obtain a new CSRF (Cross-Site Request Forgery) token. Every time you create an alarm, you must generate a new CSRF token. The token is in the csrf property of the resulting JSON response.

     If you are retrieving or deleting alarms, you do not need the CSRF token, which is required only for creating alarms.

     curl --tlsv1.2 -H 'Authorization: PDAPI <API-key-id>:<API-key-token>' https://dashboard.pepperdata.com/api/csrf
     

  2. Access the create alarms API.

     This example creates an alarm with the title, “Alarm”; sets the chart-equivalent query parameters for User CPU percentage, by Host, by User “your-user”, for an upper threshold of “50%”; and overrides default email alarm alert notifications with addresses “user-1@some-domain.com” and “user-2@some-domain.com”.

     • For active API keys, use the following command format:

       curl --tlsv1.2 -H 'Authorization: PDAPI <API-key-id>:<API-key-token>' -X POST -H \
       "Content-Type: \
       application/json" -d '{"title": "Alarm", \
       "queryParams": "h=*&u=your-user&m=c_ucpupct", \
       "threshold": {"value": 50}, \
       "targetEmails": "user-1@somedomain.com,user-2@somedomain.com"}', \
       https://dashboard.pepperdata.com/{your-realm-name}/api/alarms\?csrf\=<CSRF>
       

     • For legacy API keys, use the following command format, which also shows how to add the extremumOperator parameter to create an alarm with a lower threshold instead of the default upper threshold:

       curl --tlsv1.2 --user <API-key-id>:<API-key-token> -X POST -H \
       "Content-Type: \
       application/json" -d '{"title": "Alarm", \
       "queryParams": "h=*&u=user&m=c_ucpupct", \
       "threshold": {"value": 50, "extremumOperator": "MIN"}, \
       "targetEmails": "user-1@somedomain.com,user-2@somedomain.com"}' \
       https://dashboard.pepperdata.com/{your-realm-name}/api/alarms\?csrf\=<CSRF>
       

• Retrieve All Alarms in JSON Format

  • For active API keys, use the following command format:

    curl --tlsv1.2 -H 'Authorization: PDAPI <API-key-id>:<API-key-token>' https://dashboard.pepperdata.com/{your-realm-name}/api/alarms
    

  • For legacy API keys, use the following command format:

    curl --tlsv1.2 --user <API-key-id>:<API-key-token> https://dashboard.pepperdata.com/{your-realm-name}/api/alarms
    

  Important: If encryption is enabled for the cluster, you’ll need to decrypt the returned data; see Decrypt Data Returned for Encrypted Clusters.

• Retrieve a Specific Alarm

  • For active API keys, use the following command format:

    curl --tlsv1.2 -H 'Authorization: PDAPI <API-key-id>:<API-key-token>' https://dashboard.pepperdata.com/{your-realm-name}/api/alarms/{your-alarm-id}
    

  • For legacy API keys, use the following command format:

    curl --tlsv1.2 --user <API-key-id>:<API-key-token> https://dashboard.pepperdata.com/{your-realm-name}/api/alarms/{your-alarm-id}
    

  Important: If encryption is enabled for the cluster, you’ll need to decrypt the returned data; see Decrypt Data Returned for Encrypted Clusters.

• Get a List of Firing Alarms

  • For active API keys, use the following command format:

    curl --tlsv1.2 -H 'Authorization: PDAPI <API-key-id>:<API-key-token>' https://dashboard.pepperdata.com/{your-realm-name}/api/alarms/status
    

  • For legacy API keys, use the following command format:

    curl --tlsv1.2 --user <API-key-id>:<API-key-token> https://dashboard.pepperdata.com/{your-realm-name}/api/alarms/status
    

  Important: If encryption is enabled for the cluster, you’ll need to decrypt the returned data; see Decrypt Data Returned for Encrypted Clusters.

Use a Web Browser to Access the Alarms API

Before you can access the alarms API from within a web browser, you must authenticate yourself by logging in to the Pepperdata dashboard. As long as you use the same browser session to access the API, your user authentication is applicable.

To display alarms data in a browser page, open a browser page and enter the-api-resource-you-are-querying in the browser’s address bar. For example:

https://dashboard.pepperdata.com/{your-cluster-name}/api/alarms

Programmatically Access Alarms

The commented Python examples show how to make an HTTP request to the Pepperdata REST API resource for creating an alarm and retrieving all firing alarms.

Create an Alarm

# Pepperdata REST API Python example for creating an alarm.

########################### IMPORTS ###########################

# Not required in this example, but recommended for date and time manipulation.
import datetime

# To get the Requests HTTP library, use the following: `pip install requests`
# If you do not have the pip Python package management system,
# install it from the python.org website:
# https://packaging.python.org/tutorials/installing-packages/
import requests
import os

# The authorization process (and therefore the required code imports) is
# different for recently-generated keys and legacy keys
# (keys generated before late August, 2017). Recently-generated
# keys are listed in the Active Keys section of the API Keys page
# (https://dashboard.pepperdata.com/account/apikeys); legacy keys are
# listed in the Legacy Keys section.
#
# **** IMPORTANT ****
#
# Be sure to use the correct commands (comment/uncomment the applicable
# lines) wherever you see "Active Key" or "Legacy Key" in the comments in
# this script.
#
# Legacy keys are DEPRECATED as of 2022 Oct 19. If you have one, generate a new 
# key at https://dashboard.pepperdata.com/account/apikeys and follow the 
# Active Key instructions. 
#
# *******************

# (Legacy Key) Required
#from requests.auth import HTTPBasicAuth


####################### DEFINE GLOBALS ########################

# **** IMPORTANT ****
#
# Before you run this Python example script, be sure to assign the correct
# realm name to the REALM_NAME environment variable by exporting an
# appropriate value for 'your-realm-name':
#
# export REALM_NAME='your-realm-name'
#
# *******************
REALM_NAME = os.environ['REALM_NAME']

CSRF_URL = 'https://dashboard.pepperdata.com/api/csrf'

# Base url where the Pepperdata dashboard REST API metrics
# resource for your realm is hosted
BASE_URL_REALM = 'https://dashboard.pepperdata.com/{}/api'.format(REALM_NAME)

# For Pepperdata-hosted dashboards (the default implementation),
# API access requires authentication via an API key.
# To obtain an API key, go to the following web page:
# https://dashboard.pepperdata.com/account/apikeys
#
# The "ID" is the portion of the API key before the ":"
# The password (secret) token is the portion of the API key after the ":"
# **** IMPORTANT ****
#
# Before you run this Python example script, be sure to assign the correct
# values to the API_KEY_ID and API_KEY_SECRET environment variables by
# exporting the correct values for 'your-api-key-id' and 'your-api-key-secret':
#
# export API_KEY_ID='your-api-key-id'
# export API_KEY_SECRET='your-api-key-secret'
#
# *******************
API_KEY_ID = os.environ['API_KEY_ID']
API_KEY_SECRET = os.environ['API_KEY_SECRET']

# (Active Key) Required header
HEADERS = {
  'Accept': 'application/json',
  'Authorization': 'PDAPI ' + API_KEY_ID + ":" + API_KEY_SECRET
}
# (Legacy Key) Required header
#HEADERS = {'Accept': 'application/json'}
#basicAuth=HTTPBasicAuth(API_KEY_ID, API_KEY_SECRET)


# Get a CSRF (Cross-Site Request Forgery) token

response = requests.get(CSRF_URL, headers=HEADERS)
response.raise_for_status()
csrf = response.json()["csrf"]

# Assemble the parameters to easily pass to the HTTP request portion.
# This example creates an alarm with the title, "your-new-alarm-title";
# sets the chart-equivalent query parameters for User CPU percentage,
# by Host, by User "your-user", for an upper threshold of "50 %"; and
# configures email override addresses ("user-1@some-domain.com" and
# "user-2@some-domain.com") for this alarm's alerts.
new_alarm = {
    "title": "your-new-alarm-title",
    "queryParams": "h=*&u=your-user&m=c_ucpupct",
    "threshold": {"value": 50},
    "targetEmails": "user-1@somedomain.com,user-2@somedomain.com"
}

########### MAKE THE REQUEST AND PRINT THE RESPONSE ###########

# (Active Key) request:
try:
    response = requests.post(BASE_URL_REALM + "/alarms?csrf=" + csrf,
                             json=new_alarm, headers=HEADERS)
# (Legacy Key) request:
#    response = requests.post(BASE_URL_REALM + "/alarms?csrf=" + csrf,
#                             json=new_alarm, auth=basicAuth, headers=HEADERS)
    print response
except:
    print "Error receiving response from server."

Retrieve Alarms

# Pepperdata REST API Python example for retrieving firing alarms.

########################### IMPORTS ###########################

# Not required in this example, but recommended for date and time manipulation.
import datetime

# To get the Requests HTTP library, use the following: `pip install requests`
# If you do not have the pip Python package management system,
# install it from the python.org website:
# https://packaging.python.org/tutorials/installing-packages/
import requests
import os

# The authorization process (and therefore the required code imports) is
# different for recently-generated keys and legacy keys
# (keys generated before late August, 2017). Recently-generated
# keys are listed in the Active Keys section of the API Keys page
# (https://dashboard.pepperdata.com/account/apikeys); legacy keys are
# listed in the Legacy Keys section.
#
# **** IMPORTANT ****
#
# Be sure to use the correct commands (comment/uncomment the applicable
# lines) wherever you see "Active Key" or "Legacy Key" in the comments in
# this script.
#
# Legacy keys are DEPRECATED as of 2022 Oct 19. If you have one, generate a new 
# key at https://dashboard.pepperdata.com/account/apikeys and follow the 
# Active Key instructions. 
#
# *******************

# (Legacy Key) Required
#from requests.auth import HTTPBasicAuth


####################### DEFINE GLOBALS ########################

# Name of the your cluster/realm configured on Pepperdata
# **** IMPORTANT ****
#
# Before you run this Python example script, be sure to assign the correct
# realm name to the REALM_NAME environment variable by exporting an
# appropriate value for 'your-realm-name':
#
# export REALM_NAME='your-realm-name'
#
# *******************
REALM_NAME = os.environ['REALM_NAME']

# Base url where the Pepperdata dashboard REST API metrics
# resource for your realm is hosted
ALARMS_URL = 'https://dashboard.pepperdata.com/{}/api/alarms/status'.format(REALM_NAME)

# For Pepperdata-hosted dashboards (the default implementation),
# API access requires authentication via an API key.
# To obtain an API key, go to the following web page:
# https://dashboard.pepperdata.com/account/apikeys
#
# The "ID" is the portion of the API key before the ":"
# The password (secret) token is the portion of the API key after the ":"
# **** IMPORTANT ****
#
# Before you run this Python example script, be sure to assign the correct
# values to the API_KEY_ID and API_KEY_SECRET environment variables by
# exporting the correct values for 'your-api-key-id' and 'your-api-key-secret':
#
# export API_KEY_ID='your-api-key-id'
# export API_KEY_SECRET='your-api-key-secret'
#
# *******************
API_KEY_ID = os.environ['API_KEY_ID']
API_KEY_SECRET = os.environ['API_KEY_SECRET']

# (Active Key) Required header
HEADERS = {
  'Accept': 'application/json',
  'Authorization': 'PDAPI ' + API_KEY_ID + ":" + API_KEY_SECRET
}
# (Legacy Key) Required header
#HEADERS = {'Accept': 'application/json'}


########### MAKE THE REQUEST AND PARSE THE RESPONSE ###########

# Send the request to the Pepperdata REST API alarms status resource,
# passing the base url, the username and password,
# and the required header, which you defined previously.

# (Active Key) request:
try:
    response = requests.get(ALARMS_URL, headers=HEADERS)
# (Legacy Key) request:
#try:
#    auth = HTTPBasicAuth(API_KEY_ID, API_KEY_SECRET)
#    response = requests.get(ALARMS_URL, auth=auth, headers=HEADERS)
except:
    print ("Error receiving response from server.")


# Parse the response as JSON
json_response = response.json()

# Loop through all the alarms and print out any that are firing
for alarm_info in json_response['alarmStatuses']:
    if alarm_info['firing']:
        print "Alarm {} is firing. Chart {}".format(alarm_info['alarm']['title'],
                                                    alarm_info['chartUrlOfLastFire'])