# 使用 Amazon CloudWatch 指标监控 REST API 执行
<a name="monitoring-cloudwatch"></a>

您可以使用 CloudWatch 监控 API 执行，这将从 API Gateway 收集原始数据，并将数据处理为便于阅读的近乎实时的指标。这些统计数据会保存 15 个月，从而使您能够访问历史信息，并能够更好地了解您的 Web 应用程序或服务的执行情况。默认情况下，API Gateway 指标数据会在一分钟时段内自动发送到 CloudWatch。有关更多信息，请参阅 *Amazon CloudWatch 用户指南* 中的[什么是 Amazon CloudWatch？](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)

您可以通过多种方式分析 API Gateway 报告的指标所提供的信息。下面的列表显示了指标的一些常见用法，这些内容是帮助您开始使用的建议：
+ 监控 **IntegrationLatency** 指标以衡量后端的响应能力。
+ 监控 **Latency** 指标以衡量 API 调用的整体响应能力。
+ 监控 **CacheHitCount** 和 **CacheMissCount** 指标以优化缓存容量，从而实现所需的性能。

**Topics**
+ [Amazon API Gateway 维度和指标](api-gateway-metrics-and-dimensions.md)
+ [使用 API Gateway 中的 API 控制面板查看 CloudWatch 指标](how-to-api-dashboard.md)
+ [在 CloudWatch 控制台中查看 API Gateway 指标](metrics_dimensions_view_in_cloud_watch.md)
+ [在 CloudWatch 控制台中查看 API Gateway 日志事件](view-cloudwatch-log-events-in-cloudwatch-console.md)
+ [AWS 中的 API Gateway 监控工具](monitoring_automated_manual.md)

# Amazon API Gateway 维度和指标
<a name="api-gateway-metrics-and-dimensions"></a>

下面列出 API Gateway 发送给 Amazon CloudWatch 的指标和维度。有关更多信息，请参阅 [使用 Amazon CloudWatch 指标监控 REST API 执行](monitoring-cloudwatch.md)。

## API Gateway 指标
<a name="api-gateway-metrics"></a>

Amazon API Gateway 每分钟向 CloudWatch 发送一次指标数据。

`AWS/ApiGateway` 命名空间包括以下指标。


| 指标 | 说明 | 
| --- | --- | 
|  4XXError |  在给定期间捕获的客户端错误数。 API Gateway 将修改后的网关响应状态代码计为 4XXError 错误。 `Sum` 统计数据表示此指标，即给定期间内 4XXError 错误的总计数。`Average` 统计数据表示 4XXError 错误率，即 4XXError 错误的总计数除以该期间中的请求总数。分母对应于 Count 指标 (见下)。 Unit: Count  | 
|  5XXError  |  在给定期间捕获的服务器端错误数。 `Sum` 统计数据表示此指标，即给定期间内 5XXError 错误的总计数。`Average` 统计数据表示 5XXError 错误率，即 5XXError 错误的总计数除以该期间中的请求总数。分母对应于 Count 指标 (见下)。 Unit: Count  | 
|  CacheHitCount  |  在给定期间内从 API 缓存中提供的请求数。 `Sum` 统计数据表示此指标，即给定期间内缓存命中的总计数。`Average` 统计数据表示缓存命中率，即缓存命中的总计数除以该期间中的请求总数。分母对应于 Count 指标 (见下)。 Unit: Count  | 
|  CacheMissCount  |  在启用 API 缓存时，在给定期间内由后端所服务的请求的数量。 `Sum` 统计数据表示此指标，即指定期间内缓存未命中的总计数。`Average` 统计数据表示缓存未命中率，即缓存未命中的总计数除以该期间中的请求总数。分母对应于 Count 指标 (见下)。 Unit: Count  | 
|  Count  |  给定期间内的 API 请求总数。 `SampleCount` 统计数据表示此指标。 Unit: Count  | 
|  IntegrationLatency  |  从 API Gateway 将请求中继到后端到其从后端收到响应所经过的时间。 Unit: Millisecond  | 
|  Latency  |  从 API Gateway 从客户端收到请求到其将响应返回给客户端所经过的时间。延迟包括集成延迟和其他 API Gateway 开销。 Unit: Millisecond  | 

## 指标的维度
<a name="api-gateway-metricdimensions"></a>

您可以使用下表中的维度筛选 API Gateway 指标。

**注意**  
API Gateway 先从 ApiName 维度中删除非 ASCII 字符，然后再将指标发送到 CloudWatch。如果 APIName 不包含任何 ASCII 字符，则 API ID 将用作 ApiName。


| 维度 | 说明 | 
| --- | --- | 
|  ApiName  |  针对具有指定 API 名称的 REST API 筛选 API Gateway 指标。  | 
|  ApiName, Method, Resource, Stage  |  针对具有指定 API 名称、阶段、资源和方法的 API 方法筛选 API Gateway 指标。 除非您明确启用了详细的 CloudWatch 指标，否则 API Gateway 不会发送这些指标。在控制台中，选择一个阶段，然后对于**日志和跟踪**，选择**编辑**。选择**详细指标**，然后选择**保存更改**。或者，您也可以调用 [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) AWS CLI 命令，以将 `metricsEnabled` 属性更新为 `true`。 启用这些指标会对您的账户额外计费。有关定价信息，请参阅 [Amazon CloudWatch 定价](https://aws.amazon.com/cloudwatch/pricing/)。  | 
|  ApiName, Stage  |  针对具有指定 API 名称和阶段的 API 方法筛选 API Gateway 指标。  | 

# 使用 API Gateway 中的 API 控制面板查看 CloudWatch 指标
<a name="how-to-api-dashboard"></a>

您可以使用 API Gateway 控制台中的 API 控制面板在 API Gateway 中显示已部署 API 的 CloudWatch 指标。它们显示为一段时间内 API 活动的总结。

**Topics**
+ [先决条件](#how-to-api-dashboard-prerequisites)
+ [在控制面板中检查 API 活动](#how-to-api-dashboard-console)

## 先决条件
<a name="how-to-api-dashboard-prerequisites"></a>

1. 您必须已在 API Gateway 中创建 API。按照中的说明进行操作[开发 API Gateway 中的 REST API](rest-api-develop.md)

1. 您必须至少部署一次 API。按照中的说明进行操作[在 API Gateway 中部署 REST API。](how-to-deploy-api.md)

## 在控制面板中检查 API 活动
<a name="how-to-api-dashboard-console"></a>

1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。

1. 选择一个 API。

1. 在主导航窗格中，选择**控制面板**。

1. 对于**阶段**，选择所需的阶段。

1. 选择**日期范围**以指定日期范围。

1. 如果需要请刷新，并查看标题分别为 **API 调用**、**延迟**、**集成延迟**、**延迟**、**4xx 错误**和 **5xx 错误**的独立图表中显示的各个指标。
**提示**  
要检查方法级别的 CloudWatch 指标，请确保您已在方法级别启用 CloudWatch Logs。有关如何设置方法级别日志记录的更多信息，请参阅[覆盖阶段级别设置](set-up-stages.md#how-to-method-override)。

# 在 CloudWatch 控制台中查看 API Gateway 指标
<a name="metrics_dimensions_view_in_cloud_watch"></a>

指标的分组首先依据服务命名空间，然后依据每个命名空间内的各种维度组合。要查看 API 的方法级指标，请开启详细指标。有关更多信息，请参阅 [修改阶段设置](set-up-stages.md#how-to-stage-settings)。

**使用 CloudWatch 控制台查看 API Gateway 指标**

1. 通过以下网址打开 CloudWatch 控制台：[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)。

1. 如果需要，更改 AWS 区域。从导航栏中，选择 AWS 资源所在的区域。

1. 在导航窗格中，选择**指标**。

1. 在**全部指标**选项卡上，选择 **API Gateway**。

1.  要按阶段查看指标，请选择**按阶段**面板。然后，选择您的 API 和指标名称。

1. 要按特定 API 查看指标，请选择**按 Api 名称**面板。然后，选择您的 API 和指标名称。

**使用AWS CLI 查看指标**

1. 使用以下 [list-metrics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/list-metrics.html) 命令列出指标：

   ```
   aws cloudwatch list-metrics --namespace "AWS/ApiGateway"
   ```

   创建指标后，请等待最多 15 分钟让指标显示出来。要更快地查看指标统计信息，请使用 [get-metric-data](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/update-domain-name.html) 或 [get-metric-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/update-domain-name.html)。

1. 使用以下 [get-metrics-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/get-metric-statistics.html) 命令，以 5 分钟为间隔，查看一段时间内的平均值：

   ```
   aws cloudwatch get-metric-statistics --namespace AWS/ApiGateway --metric-name Count --start-time 2011-10-03T23:00:00Z --end-time 2017-10-05T23:00:00Z --period 300 --statistics Average
   ```

# 在 CloudWatch 控制台中查看 API Gateway 日志事件
<a name="view-cloudwatch-log-events-in-cloudwatch-console"></a>

下一节介绍必要的先决条件以及如何在 CloudWatch 控制台中查看 API Gateway 日志事件。

## 先决条件
<a name="view-cloudwatch-log-event-prerequisites"></a>

1. 您必须已在 API Gateway 中创建 API。按照中的说明进行操作[开发 API Gateway 中的 REST API](rest-api-develop.md)

1. 必须至少部署和调用一次 API。按照[在 API Gateway 中部署 REST API。](how-to-deploy-api.md)和[调用 API Gateway 中的 REST API](how-to-call-api.md)中的说明操作。

1. 您必须为某个阶段启用了 CloudWatch 日志。按照[为 API Gateway 中的 REST API 设置 CloudWatch 日志记录](set-up-logging.md)中的说明进行操作。

## 使用 CloudWatch 控制台查看记录的 API 请求和响应
<a name="view-cloudwatch-log-event"></a>

1. 通过以下网址打开 CloudWatch 控制台：[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)。

1. 如果需要，更改 AWS 区域。从导航栏中，选择 AWS 资源所在的区域。有关更多信息，请参阅[区域和端点](https://docs.aws.amazon.com/general/latest/gr/rande.html)。

1. 在导航窗格中，依次选择**日志**和**日志组**。

1. 在**日志组**表中，选择 **API-Gateway-Execution-Logs\$1\$1rest-api-id\$1/\$1stage-name\$1** 名称的日志组。

1.  在**日志流**表下，选择日志流。您可以使用时间戳来帮助查找感兴趣的日志流。

1. 选择**文本**可查看原始文本，选择**行**可逐行查看事件。

**重要**  
 CloudWatch 允许您删除日志组或流。请勿手动删除 API Gateway API 日志组或流；让 API Gateway 管理这些资源。手动删除日志组或流可能会导致未记录 API 请求和响应。如果出现这种情况，您可以删除 API 的整个日志组并重新部署 API。这是因为 API Gateway 会在部署时为某个 API 阶段创建日志组或日志流。

# AWS 中的 API Gateway 监控工具
<a name="monitoring_automated_manual"></a>

AWS 为您提供了各种可用于监控 API Gateway 的工具。您可以配置其中的一些工具来为您自动执行监控任务，但其他工具需要手动干预。建议您尽可能实现监控任务自动化。

## 中的自动监控工具AWS
<a name="monitoring_automated_tools"></a>

您可以使用以下自动化监控工具来监控 API Gateway，并在出现错误时进行报告：
+ **Amazon CloudWatch 警报** – 按您指定的时间段观察单个指标，并根据相对于给定阈值的指标值在若干时间段内执行一项或多项操作。具体操作是将一条通知已发送到某个 Amazon Simple Notification Service（Amazon SNS）主题或 Amazon EC2 Auto Scaling 策略。CloudWatch 告警不调用操作，因为这些操作处于特定状态；状态必须改变并保持指定时间。有关更多信息，请参阅[使用 Amazon CloudWatch 指标监控 REST API 执行](monitoring-cloudwatch.md)。
+ **Amazon CloudWatch Logs**：监控、存储和访问来自 AWS CloudTrail 或其他来源的日志文件。有关更多信息，请参阅《Amazon CloudWatch 用户指南》**中的 [What is CloudWatch Logs?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html)
+ **Amazon EventBridge（以前称为 CloudWatch Events）**– 匹配事件并将事件传送到一个或多个目标函数或流，来进行更改、捕获状态信息和采取纠正措施。有关更多信息，请参阅《EventBridge 用户指南》**中的 [What Is Amazon EventBridge?](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html)
+ **AWS CloudTrail 日志监控**：在账户间共享日志文件，通过将 CloudTrail 日志文件发送到 CloudWatch Logs 来进行实时监控，用 Java 编写日志处理应用程序，验证 CloudTrail 提供的日志文件未发生更改。有关更多信息，请参见《AWS CloudTrail 用户指南》**的[使用 CloudTrail 日志文件](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-working-with-log-files.html)。

## 手动监控工具
<a name="monitoring_manual_tools"></a>

监控 API Gateway 的另一个重要环节是手动监控 CloudWatch 警报未涵盖的那些项。API Gateway、CloudWatch 和其他AWS控制台控制面板提供您的AWS环境状态的概览视图。建议您还要查看有关 API 执行的日志文件。
+ API Gateway 控制面板显示指定时间段内给定 API 阶段的以下统计数据：
  + **API 调用**
  + **缓存命中**（仅当启用 API 缓存时）。
  + **缓存未命中**（仅当启用 API 缓存时）。
  + **延迟**
  + **集成延迟**
  + **4XX 错误**
  + **5XX 错误**
+ CloudWatch 主页显示：
  + 当前警报和状态
  + 告警和资源图表
  + 服务运行状况

  此外，还可以使用 CloudWatch 执行以下操作：
  + 创建[自定义控制面板](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html)以监控您关心的服务
  + 绘制指标数据图，以排除问题并弄清楚趋势
  + 搜索并浏览您所有的 AWS 资源指标
  + 创建和编辑警报以接收有关问题的通知

## 创建 CloudWatch 警报以监控 API Gateway 指标
<a name="creating_alarms"></a>

您可以创建在警报改变状态时发送 Amazon SNS 消息的 CloudWatch 警报。警报会每隔一段时间（由您指定）监控一个指标，并根据相对于给定阈值的指标值每隔若干个时间段执行一项或多项操作。操作是一个发送到 Amazon SNS 主题或自动扩缩策略的通知。警报只会调用操作进行持续的状态变更。CloudWatch 告警不调用操作，因为这些操作处于特定状态；状态必须改变并保持指定时间。