如何开启 CloudWatch Logs 以对 API Gateway REST API 或 WebSocket API 进行问题排查？

上次更新日期：2021 年 3 月 10 日

要对 API Gateway REST API 或 WebSocket API 进行问题排查，请使用 Amazon CloudWatch Logs 开启执行日志记录和访问日志记录功能。

注意：HTTP API 目前只支持访问日志记录，且这些 API 的日志记录设置不同。有关更多信息，请参阅为 HTTP API 配置日志记录。

执行日志包含可用于识别和排查大多数 API 错误的信息。例如：

• 您的 API 接收到的请求。
• 来自您的 API 的集成后端响应。
• 由 Lambda 授权方提供的响应。
• AWS 集成终端节点的 requestId。
• 有关所提供的 API 密钥是否已获得授权的信息。

访问日志包含哪些人访问了您的 API 及其访问方式的详细信息，您还可以用这些信息进行 API 错误的问题排查。有关每种日志记录类型的更多信息，请参阅 API Gateway 的 CloudWatch Log 格式。

1.    在 AWS Identity and Access Management (IAM) 控制台的左侧导航窗格中，选择角色。

2.    在角色窗格中，选择创建角色。

3.    在 Create role（创建角色）页面执行以下操作：
对于 Select type of trusted entity（选择受信任实体类型），选择 AWS Service（AWS 服务）。
对于 Choose a use case（选择使用案例），选择 API Gateway。
对于 Select your use case（选择您的使用案例），请选择 API Gateway。
选择 Next: Permissions（下一步：权限）。

4.    请注意，在 Attached permissions policies（附加权限策略）下，系统会默认选中 AWS 托管策略 AmazonAPIGatewayPushToCloudWatchLogs。此策略拥有所有必需的权限。

5.    选择 Next: Tags（下一步：标签）。

6.    （可选）添加标签。

7.    选择下一步: 检查。

8.    在 Review（审核）下执行以下操作：
在角色名称字段中为角色输入一个有意义的名称。
（可选）对于角色描述，根据您的首选项编辑描述。
选择 Create Role（创建角色）。

9.    在 Roles（角色）窗格中的搜索栏中，输入您创建的角色的名称。然后，从搜索结果中选择角色。

10.    在 Summary（摘要）窗格中，复制角色 ARN。在下一部分中您将需要使用此 Amazon 资源名称 (ARN)。

有关更多信息，请参阅 CloudWatch 日志记录权限。

注意：如果您正在跨不同 AWS 区域开发多个 API，则请在每个区域中完成以下步骤。

1.    在 API Gateway 控制台中的 API 窗格上，选择您创建的 API 的名称。

2.    在左侧导航窗格下方的 Client Certificates（客户端证书）部分下方，选择 Settings（设置）。

3.    在 Settings（设置）下，为 CloudWatch 日志角色 ARN 粘贴您复制的 IAM 角色 ARN。

4.    选择 Save（保存）。
注意：控制台不会确认 ARN 是否已保存。

1.    在 API Gateway 控制台中，为您的 API 找到 Stage Editor（阶段编辑器）。

2.    在 Stage Editor（阶段编辑器）窗格中，选择 Logs/Tracing（日志/跟踪）选项卡。

3.     在 Logs/Tracing（日志/跟踪）选项卡上的 CloudWatch Settings（CloudWatch 设置）下，执行以下操作以开启执行日志记录：
选择 Enable CloudWatch Logs（启用 CloudWatch Logs）复选框。
对于 Log level（日志级别），选择 INFO（信息）以针对所有请求生成执行日志。或者，选择 ERROR（错误）以仅针对导致错误的 API 请求生成执行日志。
对于 REST API，选择 Log full requests/responses data（记录完整请求/响应数据）复选框。或者，对于 WebSocket API，选择 Log full message data（记录完整消息数据）复选框。

4.    在 Custom Access Logging（自定义访问日志记录）下，执行以下操作以开启访问日志记录：
选择 Enable Access Logging（启用访问日志记录）复选框。
对于 Access Log Destination ARN（访问日志目标 ARN），输入 CloudWatch 日志组或 Amazon Kinesis Data Firehose 流的 ARN。
输入 Log Format（日志格式）。对于指导，选择 CLF、JSON、XML 或 CSV，从而以该格式查看示例。

5.    选择 Save Changes（保存更改）。
注意：控制台不会确认设置是否已保存。

有关更多信息，请参阅使用 API Gateway 控制台设置 CloudWatch API 日志记录。

1.    使用您的客户端应用程序或者 Postman 应用程序、wscat（适用于 WebSocket API）等工具向您的 API 发送新请求。

2.    在 CloudWatch 控制台左侧导航窗格中的 Logs（日志）下，选择 Log Groups（日志组）。

3.    在 Log Groups（日志组）列表中，选择您要调试的 API 的日志组。
对于 REST API，日志组名称使用以下格式：API-Gateway-Execution-Logs_apiId/stageName。
对于 WebSocket API，日志组名称使用以下格式：/aws/apigateway/apiId/stageName。
注意：访问日志位于您在开启访问日志记录时为其指定 ARN 的日志组中。

4.    在 Log Streams（日志流）的列表中，选择具有最新的上一次事件时间的日志流。此选择将允许您查看包含请求执行或访问详细信息的消息。

有关更多信息，请参阅在 CloudWatch 控制台中查看 API Gateway 日志事件。