Use the anomaly detection API

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

Most of the APIs that you use to create and manage anomaly alerts and to gather anomaly metrics are the same as the ones you use with fixed alerts. The following alert APIs work in the same way for both fixed and anomaly alerts:

• Get an alert - Get a fixed or anomaly alert definition.
• Get alert history - Get alert history metrics.
• Delete an alert - Delete a fixed or anomaly alert definition.
• Get alert instance - Get information about a triggered alert.
• Get alert count - Get the total count of alerts.

However, some APIs have additional properties used to support anomaly alerts, including:

• Get alerts - List all alerts, including fixed and anomaly alerts.
• Create an alert - Create a fixed or anomaly alert.
• Update an alert - Update a fixed or anomaly alert definition.

Setting $ACCESS_TOKEN

All of the API calls shown below pass your credentials in an environment variable called $ACCESS_TOKEN. 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 these examples, see Use cURL.

Get alerts

By default, the Get alerts API returns information about all defined alerts. This API now takes query parameters to let you filter the results:

• enabled - If true specifies to return only enabled alerts. The default value is false.
• alertType - Specifies the type of alert to return. The allowed values are runtime, the default, cert.
• alertSubType - Specifies the alert subtype to return. The default value is unset, meaning return all alert subtypes. Specify anomaly to return anomaly alerts.

For example, use the following API call to return only enable alerts for the organization named myorg:

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
'https://apimonitoring.enterprise.apigee.com/alerts?org=myorg&enabled=true'

The following call returns only anomaly alerts, both enabled and disabled:

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
'https://apimonitoring.enterprise.apigee.com/alerts?org=myorg&alertType=runtime&alertSubType=anomaly'

Create or update an anomaly alert

Use the same APIs to create or update an anomaly alert as you currently do for a fixed alert. The body of the API call to create or update an anomaly alert is the same as used for a fixed alert, with the following changes:

• You must add the following new properties to specify that the alert is an anomaly alert:

  "alertType": "runtime"
  "alertSubType": "anomaly"

  The default values of these properties are:

  "alertType": "runtime"
  "alertSubType": "fixed"

• In the conditions array:

  • The metrics property only takes the values of:

    • count - Raise an alert on HTTP error counts.
    • totalLatency - Raise an alert for latency.
  • The threshold property takes a string instead of a number. Supported values include: slight, moderate, and severe.
  • The durationSeconds and comparator properties are not supported.

• In the dimensions element of the conditions array:

  • You must set the value of the proxy property to ALL.
  • The statusCode property only supports a value of 4xx, 503, 504, and 5xx.
  • The developerApp, collection, faultCodeCategory, faultCodeSubCategory, faultCodeName properties are not supported.
• The reportEnabled property is not supported for anomaly alerts.

The following example API call creates an anomaly alert that is triggered when 5xx status codes occur at a moderate rate for all API proxies 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 Anomaly Alert",
     "description":"My 5xx alert",
     "environment":"prod",
     "enabled":true,
     "alertType": "runtime",
     "alertSubType": "anomaly",
     "conditions":[
     {
        "description":"",
        "dimensions":{
            "org":"myorg",
            "env":"prod",
            "proxy":"ALL",
            "region":"ANY",
            "statusCode":"5xx"
        },
        "metric":"count",
        "threshold": "moderate"
     }
     ],
     "notifications":[{
         "channel":"email",
         "destination":"ops@acme.com"
     }],
     "playbook":"http://acme.com/myplaybook.html",
     "throttleIntervalSeconds":3600
    }'

Use the events API with anomalies

Use the /metrics/events API to get all events in an organization for a specified time interval. The list of events includes anomalies detected by Edge and any triggered alerts. The alerts can include both fixed and anomaly alerts.

By default, the API returns all events for the previous hour. Use the from and to query parameters to specify a different duration. The from and to query parameter values to specify a different duration.

For example, the following API call returns all events in the organization myorg for the previous 12 hours:

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
"https://apimonitoring.enterprise.apigee.com/metrics/events?org=myorg&from=-12h&to=now"

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.

The next call returns all anomaly events with a moderate threshold for the past 24 hours:

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
"https://apimonitoring.enterprise.apigee.com/metrics/events?org=myorg&type=anomaly&threshold=moderate&from=-24h&to=now"

Only the org query parameter is required for this API. Along with the query params described in the API doc at /metrics/events, this API supports the following options to support anomaly detection: