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

上次更新时间:2020 年 11 月 10 日

我需要调试正在开发的 Amazon API Gateway REST API 或 WebSocket API 的错误。如何启用日志记录功能,以对我的 API 进行问题排查?

简短描述

要对正在开发的 API Gateway REST API 或 WebSocket API 进行问题排查,请启用到 Amazon CloudWatch Logs 的执行日志记录和访问日志记录。

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

执行日志中包含非常有用的信息,您可以使用这些信息来识别和修复您的 API 的大多数错误。这些信息包括:

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

解决方法

创建 IAM 角色以便将日志记录到 CloudWatch

  1. AWS Identity and Access Management (IAM) 控制台的左侧导航窗格中,选择角色
  2. 角色窗格中,选择创建角色
  3. 创建角色页面执行以下操作:
    对于选择受信任实体的类型,选择 AWS 服务
    对于选择将使用此角色的服务,选择 API Gateway
    选择下一步: 权限
  4. 请注意,在附加权限策略下,系统会默认选中 AWS 托管策略 AmazonAPIGatewayPushToCloudWatchLogs。此策略拥有所有必需的权限。
  5. 选择下一步: 标签
  6. (可选)如果您愿意,也可添加标签,然后选择下一步: 审核
  7. 审核下执行以下操作:
    角色名称字段中为角色输入一个有意义的名称。
    (可选)对于角色描述,根据您的首选项编辑描述。
    选择创建角色
  8. 在搜索栏中的角色窗格中,输入您创建的角色的名称,然后从搜索结果中选择该角色。
  9. 摘要窗格中,复制角色 ARN。在下一部分中您将需要使用此 Amazon 资源名称 (ARN)

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

在 API Gateway 控制台中添加 IAM 角色

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

  1. API Gateway 控制台中的 API 窗格上,选择您创建的 API 的名称。
  2. 在左侧导航窗格的底部,选择设置
  3. 设置下,为 CloudWatch 日志角色 ARN 粘贴您复制的 IAM 角色 ARN。
  4. 选择保存
    注意:控制台不会确认 ARN 是否保存成功。

针对您的 API 和阶段启用日志记录

  1. API Gateway 控制台中,为您的 API 找到“阶段编辑器”
  2. 阶段编辑器窗格中,选择日志/跟踪选项卡。
  3. 日志/跟踪选项卡上的 CloudWatch 设置下,执行以下操作以启用执行日志记录:
    选择启用 CloudWatch Logs 复选框。
    对于日志级别,选择信息以针对所有请求生成执行日志。或者,选择错误以仅针对导致错误的 API 请求生成执行日志。
    针对 REST API 选择记录完整请求/响应数据复选框。或者,针对 WebSocket API 选择记录完整消息数据复选框。
  4. 自定义访问日志记录下,执行以下操作以启用访问日志记录:
    选择启用访问日志记录复选框。
    对于访问日志目标 ARN,输入 CloudWatch 日志组Amazon Kinesis Data Firehose 流的 ARN。
    输入日志格式。对于指导,您可以选择 CLFJSONXMLCSV,从而以该格式查看示例。
  5. 选择保存更改
    注意:控制台不会确认设置是否保存成功。

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

测试您的日志记录功能设置

  1. 使用您的客户端应用程序或者 Postman 应用程序wscat(适用于 WebSocket API)等工具向您的 API 发送新请求。
  2. CloudWatch 控制台左侧导航窗格中的日志下,选择日志组
  3. 日志组列表中,选择您要调试的 API 的日志组。
    对于 REST API,日志组名称使用以下格式:API-Gateway-Execution-Logs_apiId/stageName
    对于 WebSocket API,日志组名称使用以下格式:/aws/apigateway/apiId/stageName
    注意:访问日志位于您在启用访问日志记录时为其指定 ARN 的日志组中。
  4. 日志流列表中,选择拥有最新事件时间的日志流,以查看包含请求执行或访问详细信息的消息。

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