viewing Apigee X documentation.
View Apigee Edge documentation.
One of the main purposes of API Monitoring is to keep you informed of unusual events or patterns, such as spikes in traffic or latencies. To track events like these, you can set up alerts, which are triggered when a specified event occurs. An actual event that triggers an alert is called an incident.
You can set specific rules for an alert—for example, it might be triggered by a 500 response code (Internal Service Error) on a proxy. When an incident for the alert occurs, you can view its details in the Events pane of the Cloud console Alerting dashboard.
If you want to be notified when a particular alert is triggered, you can set up a notification for the alert. When an incident occurs, Apigee sends you a notification with a summary of the event, including links to the Cloud console and the Apigee UI, for further investigation.
There are two types of alerts in API Monitoring:
- Metric-based alerts, which are triggered by changes in API metrics.
- Log-based alerts, which are based on API data stored by Cloud logging.
Metric-based alerts are triggered when a metric for API data reaches a specified level, or starts to change rapidly. You define an alert rule using two main properties:
- The metric: The quantity that triggers the alert—for example, number of requests.
- The threshold: The level that the metric must reach to trigger the alert.
Initial steps for creating a metric-based alert
To create a metric-based alert, start by doing the steps below.
Open the Create alerting policy dashboard in the Google Cloud console.
Note: Open the Create alerting policy dashboard in a new tab if you want to follow the steps below.
- Click ADD CONDITION. This opens a new window where you can add the alert condition.
- Optional: Add a title for the condition in the Untitled Condition field. We'll leave it blank for this example, in which case the condition is given a default title.
Copy and paste the following in the Find resource type and metric field:
Apigee proxy (v2)
The Target pane now appears as shown below.
The pane displays the Select a metric field, where you can specify the metric, such as total traffic or latency percentile.
After completing the initial steps above, you can continue by selecting a metric and adding conditions for the alert. The next section presents an example that shows how to do this.
Alert for response code 500 on a proxy
The next example creates an alert when a response code 500 (Internal Server Error) is returned. You can create a similar alert for any response code.
To run the example, first do the Initial steps described in the previous section. Then continue with the steps below.
In the Target pane, do the following steps:
- Add the
response_countmetric by copying the code below and pasting it in the Select a metric field.
- Add a filter for response count as follows:
- In the Filter field, click Add a filter and select response_code from the drop-down menu.
- In the next field, select =.
- In the Value field, select 500.
- Click APPLY.
You can leave the remaining fields in the Target pane unchanged, since they are not used in this example.
In the Configuration pane:
- In the Condition field, select is above.
- In the Threshold field, enter 1.
- In the For field, select most recent value.
Finally, click ADD to create the alert. This takes you back to the Create alerting policy dashboard, which displays the new condition, as shown below.
From here you can choose to either:
- Click ADD Condition to create another condition for the alert, or
- Click NEXT to go to Step 2, where you will have the option to create a notification for the alert, as described in the next section.
If you don't want to create a notification, click NEXT twice without entering anything to bypass Steps 2 and 3.
Click SAVE to save the alert.
Adding a condition: Alert for response code 500 for HTTP POST requests on a proxy
You can create multiple conditions for an alert. For example, in the alert for response code 500 on a proxy described in the previous section, you might want to add the condition that the alert is only triggered for HTTP POST requests. To do so, simply follow the same steps as in the previous example, but after step 2 in the Target section, add another filter as follows:
- Click + Add a filter and select method in the drop-down list.
- In the Value field, select POST. This specifies an HTTP POST request.
- Click Apply.
Then continue with the steps in the Configuration section. After you are finished, the alert will be triggered when the proxy receives a 500 response code from an HTTP POST request.
See Alert for combinations of response codes and HTTP methods for a related example.
Viewing incident details
An API event that triggers an alert is called an incident. You can view the details of recent incidents in the Cloud console Alerting dashboard.
Metrics and filters
This section describes the metrics and filters you can use to create metric-based alerts.
A metric is the quantity that triggers an alert, for example, number of requests. The table below shows the available metrics.
||Total number of requests received by the Apigee API proxy.|
||Total number of responses returned by the Apigee API proxy.|
||Percentile of all API proxy responses to a request.|
Filters enable you to create alerts for subsets of API data. A filter specifies a condition that defines the subset. For example, you can create an alert based on data for a single proxy.
You can choose from the following filters:
|Filter||Description||Metrics for which filter can be applied|
||Environment for the data.||All|
||Location for the data.||All|
||Proxy for the data.||All|
||Runtime version for the data.||All|
||Instance ID for the data.||All|
||HTTP method for the data.||All|
||HTTP response code for the data.||
||Fault code for the data.||
||Fault source for the data.||
||Apigee proxy response latencies percentile.||
In addition to the metric-based alerts described in the previous section, you can also create log-based alerts, which monitor API data stored by Cloud logging.
Setting up a log-based alert
The next example shows how to set up a log-based alert.
- Open the Google Cloud console in your browser.
- In the upper-left corner of the Console, open the navigation menu and select Logging > Logs Explorer.
- In the Query pane, enter a query like the example shown below.
See Create a log-based alert (Logs Explorer) for more information.
- Click Run query. The results are displayed in the Verify that the query returns the log entries you want to alert on.
Click Create alert below the Query pane.
Specify a name and a description of the alert. Note that the Alert Description field supports Markdown formatting. Once you have filled in the fields, select Next to continue.
In the Choose logs to include in the alert pane, verify that the entries below Define log entries to alert on match the query you entered in Step 3.
Select Next to continue.
Next, specify the minimum amount of time that you want to elapse between alerts for this policy. For example in the example policy below, if two log entries matching the filter are written within a 10 minute period, you will receive an alert for the first log entry that was written, but no alert for the second.
Finally, if you want to receive a notification when an alert occurs, specify a recipient in the Notification Channels field, and then click Save.
Create a notification for an alert
If you want to be notified immediately when an incident occurs, you can create a notification for the alert. When the alert is triggered, Apigee sends you a notification. You can choose any of the following channels to receive the notification:
To create a notification for an alert:
If you just created the alert (as shown in the preceding example) and are currently viewing the Create alerting policy dashboard, skip to the next step.
Otherwise, open the Policies pane in the Cloud console Alerting dashboard, and in the row for the alert you created, click the three dots icon at the end of the row and select Edit.
This opens the Edit alerting policy dashboard:
In the What do you want to track? section, click NEXT.
In the Who should be notified section, select Notification Channels, where you can choose from existing channels for receiving notifications.
If you want to create a new notification channel, select MANAGE NOTIFICATION CHANNELS. This opens the Notification channels dashboard in the Cloud console, where you can add channels. See Managing notification channels for more details.
Click NEXT. This displays the options shown below.
- In the Alert name field, enter a name for the alert.
- In the Documentation field, enter the URL for a web page that provides information on how to fix the issue that caused the alert. The URL will be included in the notification.
- Click Save to create the alert.
When an alert is triggered, you will receive a notification providing a summary of the incident and when it occurred. The notification also contains two links to help you investigate the incident:
- VIEW INCIDENT: View the incident in the Cloud console.
- VIEW IN APIGEE: View a timeline graph of API traffic and related data tables in the API Monitoring Investigate dashboard.