Monitoring API requests using Amazon CloudWatch - Amazon Elastic Compute Cloud

Monitoring API requests using Amazon CloudWatch

Important

Access to Amazon EC2 API metrics is an opt-in feature. To enable this feature for your AWS account, contact AWS Support.

You can monitor Amazon EC2 API requests using Amazon CloudWatch, which collects raw data and processes it into readable, near real-time metrics. These metrics provide a simple way to track the usage and outcomes of the Amazon EC2 API operations over time. This information gives you a better perspective on how your web applications are performing, and enables you to identify and diagnose a variety of issues. You can also set alarms that watch for certain thresholds, and send notifications or take specific actions when those thresholds are met.

For more information about CloudWatch, see the Amazon CloudWatch User Guide.

Amazon EC2 API metrics and dimensions

Metrics

The Amazon EC2 API metrics are contained in the AWS/EC2/API namespace. The following tables list the metrics available for Amazon EC2 API requests.

Metric Description

ClientErrors

The number of failed API requests caused by client errors.

These errors are usually caused by something the client did, such as specifying an incorrect or invalid parameter in the request, or using an action or resource on behalf of a user that does not have permission to use the action or resource.

Unit: Count

RequestLimitExceeded

The number of times the maximum request rate permitted by the Amazon EC2 APIs has been exceeded for your account.

Amazon EC2 API requests are throttled to help maintain the performance of the service. If your requests have been throttled, you get the Client.RequestLimitExceeded error.

Unit: Count

ServerErrors

The number of failed API requests caused by internal server errors.

These errors are usually caused by an AWS server-side error, exception, or failure.

Unit: Count

SuccessfulCalls

The number of successful API requests.

Unit: Count

Dimensions

The Amazon EC2 metric data can be filtered across all EC2 API actions. For more information about dimensions, see Amazon CloudWatch concepts.

Metric data retention

Amazon EC2 API metrics are sent to CloudWatch at 1-minute intervals. CloudWatch retains metric data as follows:

  • Data points with a period of 60 seconds (1 minute) are available for 15 days.

  • Data points with a period of 300 seconds (5 minutes) are available for 63 days.

  • Data points with a period of 3600 seconds (1 hour) are available for 455 days (15 months).

Monitoring requests made on your behalf

API requests made by AWS services on your behalf, such as requests made by service-linked roles, do not count toward your API throttling limits and they do not send metrics to Amazon CloudWatch for your account. These requests cannot be monitored using CloudWatch.

API requests made on your behalf by third-party service providers do count toward your API throttling limits and they do send metrics to Amazon CloudWatch for your account. These requests can be monitored using CloudWatch.

Billing

Standard CloudWatch pricing and charges apply. No additional charges are applied for using the Amazon EC2 API metrics. For more information, see Amazon CloudWatch Pricing.

Working with Amazon CloudWatch

Viewing CloudWatch metrics

You can view Amazon EC2 API metrics using the CloudWatch console and the command line tools.

To view metrics using the CloudWatch console

  1. Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.

  2. In the navigation pane, chose Metrics, All metrics.

  3. On the Browse tab, choose the EC2/API metric namespace.

    Note

    If the EC2/API namespace is not displayed, you do not have access to the EC2 API metrics. To request access, contact AWS Support.

  4. To view the metrics, select the metric dimension.

To view metrics using the command line tools

Use one of the following commands:

  • list-metrics (AWS CLI)

    aws cloudwatch list-metrics --namespace "AWS/EC2/API"
  • Get-CWMetricList (AWS Tools for Windows PowerShell)

    Get-CWMetricList -Namespace "AWS/EC2/API"

Creating CloudWatch alarms

You can create a CloudWatch alarm that sends an Amazon SNS message when the alarm changes state. An alarm watches a single metric over a time period that you specify. It sends a notification to an SNS topic based on the value of the metric relative to a given threshold over a number of time periods.

For example, you can create an alarm that monitors the number of DescribeInstances API requests that fail due to server-side errors. The following alarm sends an email notification when the number of DescribeInstances API request failures reach a threshold of 10 server-side errors during a 5-minute period.

To create an alarm for Amazon EC2 DescribeInstances API request server errors

  1. Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.

  2. In the navigation pane, choose Alarms, All alarms.

  3. Choose Create alarm.

  4. Choose Select metric, and the specify the following:

    1. Choose EC2/API.

      Note

      If the EC2/API namespace is not displayed, you do not have access to the EC2 API metrics. To request access, contact AWS Support.

    2. Choose Per-Action Metrics.

    3. Select the check box next to DescribeInstances that is in the same row as the ServerErrors metric name.

    4. Choose Select metric.

  5. The Specify metric and conditions page appears, showing a graph and other information about the metric and statistic that you selected.

    1. Under Metric, specify the following:

      1. For Statistic, choose Sum.

      2. For Period, verify that 5 minutes is selected.

    2. Under Conditions, specify the following:

      1. For Threshold type, choose Static.

      2. For Whenever ServerErrors is, choose Greater/Equal >=.

      3. For than..., enter 10.

    3. Choose Next.

  6. The Configure actions page appears.

    1. Under Notification, specify the following:

      1. For Alam state trigger, choose In alarm.

      2. For Select an SNS topic, choose Select an existing SNS topic or Create new topic, and complete the required fields for the notification.

      3. Choose Next.

  7. The Add name and description page appears.

    1. For Alarm name, enter a name for your alarm. The name must contain only ASCII characters.

    2. For Alarm description, enter an optional description for your alarm.

    3. Choose Next.

  8. The Preview and create page appears. Verify that the information is correct, and then choose Create alarm.

For more information, see Using Amazon CloudWatch alarms in the Amazon CloudWatch User Guide.