Set up traffic alerts

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

Use a traffic alert to raise a notification when the traffic for an environment, proxy, or region changes by a specified percentage over a time range.

You set the time range to:

  • 1 hour
  • 1 day
  • 7 days
  • 15 days (API only)
  • 30 days (API only)

The alert works by comparing the traffic for the current time range to the traffic for the previous time range. For example, you specify a one-hour time range. The alert then compares the traffic for the most recent hour against the traffic for the previous hour to compute the percent change in traffic:

percentChange = ((currentTraffic - previousTraffic) / previousTraffic) * 100

A positive value means the traffic increased, and a negative value means the traffic decreased.

You then set the threshold that triggers a traffic alert as a percentage increase or decrease in API traffic for the specified time period.

Before you set that percentage, make sure that it aligns with your normal traffic patterns. For example, if your API traffic normally fluctuates over the day with hourly traffic spikes of up to 100% at certain peak times, these spikes are normal and should not trigger an alert. However, if you then configure an alert to trigger for any 50% increase in hourly traffic, you will get unnecessary alerts for your normal traffic.

For more on alerts, see Set up alerts and notifications.

Add traffic alerts and notifications

To add traffic alerts and notifications:
  1. Click Analyze > Alert Rules in the Edge UI.
  2. Click +Alert.
  3. Enter the following general information about the alert:
    Field Description
    Alert Name Name of the alert. Use a name that describes the trigger and that will be meaningful to you. The name cannot exceed 128 characters.
    Description Description of the alert.
    Alert Type Select Total traffic. See About alert types for more.
    Environment Select the environment from the drop-down list.
    Status Toggle to enable or disable the alert.
  4. Define the threshold and dimension for the condition that will trigger the alert.
    Condition Field Description
    Threshold

    Specify to raise the alert when traffic has increased by or decreased by a specific percentage when compared to a previous time interval.

    Set the increased by percentage to a value greater than or equal to 0%. Set decreased by percentage to a value greater than or equal to 0%, and less than or equal to 100%.

    You can choose a time interval of:

    • 1 hour
    • 1 day
    • 1 week
    Dimension

    Click +Add Dimension and specify the dimension details for which to return results including the API proxy and region.

    Set a specific dimension to:

    • Proxy - Set to a specific proxy or to All proxies. Proxy does not support a value of "Any". Instead you can add a separate alert for each proxy you are interested in.
    • Region - Set to a specific region or to All regions. Region does not support a value of "Any". Instead you can add a separate alert for each region you are interested in.
  5. Click + Notification to add an alert notification.
    Notification Details Description
    Channel Select the notification channel that you want to use and specify the destination: Email, Slack, PagerDuty, or Webhook.
    Destination Specify the destination based on the selected channel type:
    • Email - Email address, such as joe@company.com
    • Slack - Slack channel URL, such as https://hooks.slack.com/services/T00000000/B00000000/XXXXX
    • PagerDuty - PagerDuty code, such as abcd1234efgh56789
    • Webhook - Webhook URL, such as https://apigee.com/test-webhook

      Note: You can specify only one destination per notification. To specify multiple destinations for the same channel type, add additional notifications.
  6. To add additional notifications, repeat the previous step.
  7. If you added a notification, set the following fields:
    Field Description
    Playbook (Optional) Free-form text field to provide a short description of recommended actions for resolving the alerts when they fire. You can also specify a link to your internal wiki or community page where you reference best practices. The information in this field will be included in the notification. The contents in this field cannot exceed 1500 characters.
    Throttle Frequency with which to send notifications. Select a value from the drop-down list.
  8. Click Save.

View alerts in the Events dashboard

When Edge detects an alert condition, it automatically logs that condition to the Events dashboard in the Edge UI. The list of events displayed in the Events dashboard includes all alerts, both fixed and cert.

To view an alert:

  1. Click Analyze > Events in the Edge UI. The new Events dashboard appears:

  2. Filter the Events dashboard by:

    • Environment
    • Region
    • Time period
  3. Select a row in the Event dashboard to show the Keystore containing the expiring cert to further investigate the alert. From the Keystore page, you can upload a new cert and delete the expiring cert.

Use the alert APIs with traffic alerts

Most of the APIs that you use to create and manage traffic alerts are the same as the ones you use with other alert types:

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

Create or update a traffic alert

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

  • Add the following new properties to specify that the alert is a traffic alert:

    "alertType": "runtime"
"alertSubType": "trafficfixed"

    The default values of these properties are:

    "alertType": "runtime"
"alertSubType": "fixed"
  • In the dimensions element of the conditions array:
    • You must set the values of the org, env, proxy, and region properties. Only those properties are supported. You can set proxy and region to ALL.
    • You must set the value of the traffic property to total.

  • In the conditions array:

    • The metrics property must have the value of trafficChange.
    • The comparator property must be set to increasedBy or decreasedBy.
    • The threshold property contains a positive value specifying a percentage increase or decrease in traffic where a value of 1.0 corresponds to 100%. For increasedBy the value must be greater than or equal to 0.0 (0%). For decreasedBy the value must be greater than or equal to 0.0 (0%) and less than or equal to 1.0 (100%).
    • The durationSeconds property must be set to one of the following values: 3600 (1 hour), 86400 (1 day), 604800 (7 days), 1296000 (15 days), 2592000 (30 days) .
  • The reportEnabled property is not supported for traffic alerts.
The following example shows how to set up an alert that is triggered when the traffic for an organization and environment increases by 50% over a one hour period. 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 Traffic Alert",
     "description":"My traffic alert",
     "environment":"prod",
     "enabled":true,
     "alertType":"runtime",
     "alertSubType":"trafficfixed",
     "conditions":[
     {
        "description":"",
        "dimensions": {
            "org":"nyorg",
            "env":"prod",
            "proxy":"ALL",
            "region":"ALL",
            "traffic":"total"
        },
        "metric": "trafficChange",
        "threshold": 0.5,
        "durationSeconds": 3600,
        "comparator": "increasedBy"
     }
     ],
     "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.

See View events for more information on using this API.

Get traffic 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, and cert.
  • alertSubType - Specifies the alert subtype to return. The default value is unset, meaning return all alert subtypes.

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 traffic alerts, both enabled and disabled:

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

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.