Managing alerts and notifications using the API

The following sections describe how to manage alerts using the API.

See Alerts API for more on the alerts API.

Set up alerts and notifications using the API

Set up alerts and notifications by issuing a POST request to the following resource: https://apimonitoring.enterprise.apigee.com/alerts

The following sections provide examples of setting up alerts and notifications using the API:

Set up a 5xx status code alert for an API proxy using the API

The following example shows how to set up an alert that is triggered when 5xx status codes occur at a rate that is greater than 100 transactions per second (TPS) for 10 minutes for the hotels API proxy in the prod environment for any region. A notification is sent to the specified email address when the alert is triggered.


curl 'https://apimonitoring.enterprise.apigee.com/alerts' \
  -X POST \
  -H 'Accept: application/json, text/plain, */*' -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
     "organization":"myorg",
     "name":"5xx Alert",
     "description":"My 5xx alert",
     "environment":"prod",
     "enabled":true,
     "conditions":[
     {
        "description":"",
        "dimensions":{
            "org":"myorg", 
            "env":"prod", 
            "proxy":"hotels",
            "region":"ANY",
            "statusCode":"5xx"
        },
        "metric":"tps",
        "threshold":100,
        "durationSeconds":600,
        "comparator":">"
     }
     ],
     "notifications":[{ 
         "channel":"email", 
         "destination":"ops@acme.com"
     }],
     "playbook":"http://acme.com/myplaybook.html",
     "throttleIntervalSeconds":3600,
     "reportEnabled":true
    }'

Set $ACCESS_TOKEN to your OAuth 2.0 access token, as described in Obtain an OAuth 2.0 access token.

For information about the cURL options used in this example, see Use cURL.

Set up a 95th percentile latency alert for an API proxy using the API

The following example shows how to set up an alert that is triggered if total response latency for the 95th percentile is greater than 100 ms for 5 minutes for the hotel API proxy in the prod environment for any region.

A notification is sent to the specified Webhook in the event the alert is triggered.


curl 'https://apimonitoring.enterprise.apigee.com/alerts' \
  -X POST \
  -H 'Accept: application/json, text/plain, */*' -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
     "organization":"myorg",
     "name":"My Alert",
     "description":"My first alert",
     "environment":"prod",
     "enabled":true,
     "conditions":[
     {
        "description":"",
        "dimensions":{
            "org":"myorg", 
            "env":"prod",
            "proxy" : "hotels",
            "region":"ANY",
            "percentile":"95"
        },
        "metric":"totalLatency",
        "threshold":100,
        "durationSeconds":300,
        "comparator":">"
     }
     ],
     "notifications":[{ "channel":"webhook", "destination":"https://apigee.com/test-webhook"}],
     "playbook":"http://acme.com/myplaybook.html",
     "throttleIntervalSeconds":3600,
     "reportEnabled":true
}'

Set $ACCESS_TOKEN to your OAuth 2.0 access token, as described in Obtain an OAuth 2.0 access token.

For information about the cURL options used in this example, see Use cURL.

Set up a 404 (Application Not Found) status code alert for all API proxies using the API

The following example shows how to set up an alert that is triggered when HTTP 4xx status codes occur at a rate that is greater than 10% for 5 minutes for a all API proxies in the prod environment for any region.

A notification is sent to the specified Slack channel when the alert is triggered.


curl 'https://apimonitoring.enterprise.apigee.com/alerts' \
  -X POST \
  -H 'Accept: application/json, text/plain, */*' -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
     "organization":"myorg",
     "name":"404 Application Not Found Alert",
     "description":"My 404 alert",
     "environment":"prod",
     "enabled":true,
     "conditions":[
     {
        "description":"",
        "dimensions":{"org":"myorg", 
            "env":"prod", 
            "proxy":"ALL",
            "region":"ANY",
            "statusCode":"4xx"},
        "metric":"proxy/rate",
        "threshold":0.05,
        "durationSeconds":300,
        "comparator":">"
     }],
     "notifications":[{ "channel":"slack", "destination":"https://hooks.slack.com/services/T00000000/B00000000/XXXXX"}],
     "playbook":"http://acme.com/myplaybook.html",
     "throttleIntervalSeconds":3600,
     "reportEnabled":true
}'

Set $ACCESS_TOKEN to your OAuth 2.0 access token, as described in Obtain an OAuth 2.0 access token.

For information about the cURL options used in this example, see Use cURL.

Set up an API proxy count alert for mission-critical APIs using the API

The following provides an example of how to set up an alert that is triggered when the 5xx code count for mission-critical APIs exceeds 200 for 5 minutes for any region.

In this example, the mission-critical APIs are captured in the Critical API Proxies collection (with UUID aeff4394-86b7-11e8-83d7-42010a840040). To obtain the UUID for a collection, see View all collections using the API.


curl 'https://apimonitoring.enterprise.apigee.com/alerts' \
  -X POST \
  -H 'Accept: application/json, text/plain, */*' -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
     "organization":"myorg",
     "name":"Proxy Count Alert",
     "description":"My proxy count alert",
     "environment":"prod",
     "enabled":true,
     "conditions":[
     {
        "description":"",
        "dimensions":{
            "collection":"aeff4394-86b7-11e8-83d7-42010a840040",
            "org":"myorg", 
            "env":"prod",
            "proxy" : "ANY",
            "region":"ANY",
            "statusCode":"5xx"
        },
        "metric":"count",
        "threshold":200,
        "durationSeconds":300,
        "comparator":">"
     }
     ],
     "notifications":[{ 
         "channel":"email", 
         "destination":"ops@acme.com"
     }],
     "playbook":"http://acme.com/myplaybook.html",
     "throttleIntervalSeconds":3600,
     "reportEnabled":true
    }'

Set $ACCESS_TOKEN to your OAuth 2.0 access token, as described in Obtain an OAuth 2.0 access token.

For information about the cURL options used in this example, see Use cURL.

Set up an error rate alert for mission-critical target services using the API

The following provides an example of how to set up an alert that is triggered when the 500 code rate for mission-critical target services exceeds 10% for 1 hour for any region.

In this example, the mission-critical target services are captured in the Critical targets collection (with UUID aeff4394-86b7-11e8-83d7-42010a840040). To obtain the UUID for a collection, see View all collections using the API.


curl 'https://apimonitoring.enterprise.apigee.com/alerts' \
  -X POST \
  -H 'Accept: application/json, text/plain, */*' -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
     "organization":"myorg",
     "name":"Error rate Alert",
     "description":"My error rate alert",
     "environment":"prod",
     "enabled":true,
     "conditions":[
     {
        "description":"",
        "dimensions":{
            "collection":"aeff4394-86b7-11e8-83d7-42010a840040",
            "org":"myorg", 
            "env":"prod",
            "proxy" : "ANY",
            "region":"ANY",
            "statusCode":"500"
        },
        "metric":"rate",
        "threshold":0.1,
        "durationSeconds":3600,
        "comparator":">"
     }
     ],
     "notifications":[{ 
         "channel":"email", 
         "destination":"ops@acme.com"
     }],
     "playbook":"http://acme.com/myplaybook.html",
     "throttleIntervalSeconds":3600,
     "reportEnabled":true
    }'

Set $ACCESS_TOKEN to your OAuth 2.0 access token, as described in Obtain an OAuth 2.0 access token.

For information about the cURL options used in this example, see Use cURL.

Set up a fault code alert for mission-critical APIs using the API

The following example shows how to set up an alert that is triggered when if one of the following conditions are met:

  • SpikeArrestViolation fault code count is greater than 10 for 5 minutes for mission-critical APIs in the prod environment for any region.
  • Count for all API protocol fault codes is greater than 3% for 5 minutes for mission-critical APIs in the prod environment for any region.

In this example, the mission-critical APIs are captured in the Critical API Proxies collection (with UUID aeff4394-86b7-11e8-83d7-42010a840040). To obtain the UUID for a collection, see View all collections using the API.

A notification is sent to the specified PagerDuty code when the alert is triggered.


curl 'https://apimonitoring.enterprise.apigee.com/alerts' \
  -X POST \
  -H 'Accept: application/json, text/plain, */*' -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
     "organization":"myorg",
     "name":"My Fault Code Alert",
     "description":"My fault code alert",
     "environment":"prod",
     "enabled":true,
     "conditions":[
     {
        "description":"",
        "dimensions": { 
            "collection":"aeff4394-86b7-11e8-83d7-42010a840040",
            "org":"myorg",
            "env":"prod",
            "proxy":"ANY",
            "region":"ANY",
            "faultCodeCategory":"Traffic Mgmt Policy",
            "faultCodeSubCategory":"Spike Arrest",
            "faultCodeName":"SpikeArrest Violation"
        },
        "metric":"proxy/count,
        "threshold":10,
        "durationSeconds":300,
        "comparator":">"
     },
     {
       "description":"",
       "dimensions": { 
           "collection":"aeff4394-86b7-11e8-83d7-42010a840040",
           "org":"myorg",
           "env":"prod",
           "proxy":"ANY",
           "region":"ANY",
           "faultCodeCategory":"API Protocol",
           "faultCodeSubCategory":"ALL"
       },
       "metric":"proxy/rate",
       "threshold":0.03,
       "durationSeconds":300,
       "comparator":">"
     }   
     ],
     "notifications":[{ "channel":"pagerduty", "destination":"abcd1234efgh56789"}],
     "playbook":"http://acme.com/myplaybook.html",
     "throttleIntervalSeconds":3600,
     "reportEnabled":true
}'

Set $ACCESS_TOKEN to your OAuth 2.0 access token, as described in Obtain an OAuth 2.0 access token.

For information about the cURL options used in this example, see Use cURL.

View all alerts and notifications

View all alerts and notifications by issuing a GET request to the following resource: https://apimonitoring.enterprise.apigee.com/alerts

You must pass the name of your organization using the org query parameter.

For example:

 curl 'https://apimonitoring.enterprise.apigee.com/alerts?org=myorg' 
    -X GET
    -H 'Accept: application/json, text/plain, */*'
    -H "Authorization: Bearer $ACCESS_TOKEN"    

The following provides an example of the response:


[{
     "uuid":"1234abcd",
     "name":"My Alert",
     "enabled":true,
     "description":"My first alert",
     "environment":"prod",
     "conditions":[
     {
        "uuid":"5678efgh",
        "description":"",
        "dimensions":{
            "env":"prod", 
            "org":"myorg", 
            "proxy":"ALL",
            "region":"ANY",
            "statusCode":"5xx"
        },
        "metric":"proxy/rate",
        "threshold":0.1,
        "durationSeconds":300,
        "comparator":"\u003e"
        "updatedBy":"-"
     },
     {
        "uuid":"9012ijkl",
        "description":"",
        "dimensions": { 
            "org":"myorg",
            "env":"prod",
            "proxy":"myproxy",
            "region":"ANY"
        },
        "metric":"p50_total",
        "threshold":3,
        "durationSeconds":900,
        "comparator":"\u003e"
        "updatedBy":"-"
     },
     {
        "description":"",
        "dimensions": { "org":"myorg",
            "env":"prod",
            "proxy":"helloworld",
            "region":"ANY",
            "faultCodeCategory":"Traffic Mgmt Policy",
            "faultCodeSubCategory":"Spike Arrest",
            "faultCodeName":"SpikeArrest Violation"
        },
        "metric":"proxy/count,
        "threshold":10,
        "durationSeconds":300,
        "comparator":"\u003e"
     },
     {
       "description":"",
       "dimensions": { 
           "org":"myorg",
           "env":"prod",
           "proxy":"ALL",
           "region":"ANY",
           "faultCodeCategory":"API Protocol",
           "faultCodeSubCategory":"HTTP",
           "faultCodeName":"HTTP BadFormData"
       },
       "metric":"proxy/rate",
       "threshold":0.03,
       "durationSeconds":300,
       "comparator":"\u003e"
     }],
    "playbook":"https://acme.com/playbook",
    "throttleIntervalSeconds":900,
    "self":"/alerts/1234abcd",
    "feed":"/o/myorg/events/1234abcd",
    "organization":"myorg",
    "notifications":[{ "channel":"email", "destination":"ops@acme.com"}],
    "updatedAt":"2018-06-22T19:07:17.356328Z",
    "updatedBy":"-"
}]