View a markdown version of this page

REST API 的执行日志记录 - Amazon API Gateway
标准执行日志记录执行日志的 Amazon CloudWatch Logs 传输

REST API 的执行日志记录

执行日志记录会记录 API Gateway 为处理 API 请求而执行的操作。记录的数据包括错误、执行跟踪、请求和响应参数值或有效载荷、Lambda 授权方使用的数据、是否需要 API 密钥，以及是否启用了使用计划。API Gateway 会从记录的数据中删除授权标头、API 密钥值和类似的敏感请求参数。

为了改善您的安全状况，我们建议您使用 ERROR 或 INFO 级别的执行日志记录。为遵守各种合规性框架，您可能需要执行此操作。有关更多信息，请参阅《AWS Security Hub User Guide》中的 Amazon API Gateway Controls。

标准执行日志记录

在阶段上启用执行日志记录后，API Gateway 会自动创建和管理 CloudWatch Logs 日志组。日志组命名为 API-Gateway-Execution-Logs_{rest-api-id}/{stage_name}。在每个日志组内，日志划分到日志流中，按上次事件时间排序。

使用标准执行日志记录时：

  • 日志事件将在 1 KB 处截断。

  • API Gateway 管理日志组名称。您无法选择日志组名称或将日志直接发送到 Amazon S3 或 Firehose。

要启用标准执行日志记录，请将阶段上的 loggingLevel 设置为 ERROR 或 INFO。无需其他配置。

权限

要启用 CloudWatch Logs，您必须向 API Gateway 授予权限，才能针对您的账户读取日志和将日志写入到 CloudWatch。AmazonAPIGatewayPushToCloudWatchLogs 托管式策略具有所需的全部权限。

请以 apigateway.amazonaws.com 作为可信实体创建一个 IAM 角色，附加上述策略，然后在您账户的 cloudWatchRoleArn 属性上设置 IAM 角色 ARN。您必须为每个要启用 CloudWatch Logs 的 AWS 区域单独设置此属性。

注意

API Gateway 将调用 AWS Security Token Service 以代入 IAM 角色，因此请确保已为该区域启用 AWS STS。有关更多信息，请参阅在AWS区域中管理AWS STS。

启用执行日志记录（控制台）

在开始之前，请将 API 部署到某个阶段，并为您的账户配置相应的 CloudWatch Logs 角色 ARN。

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

  2. 在主导航窗格上选择设置，然后在日志记录下选择编辑。

  3. 对于 CloudWatch 日志角色 ARN，请输入具有相应权限的 IAM 角色的 ARN。对于每个使用 API Gateway 创建 API 的 AWS 账户，您都需要执行一次此操作。

  4. 在主导航窗格中，选择 API，选择您的 REST API，然后选择阶段。

  5. 选择一个阶段，然后在日志和跟踪部分中，选择编辑。

  6. 从 CloudWatch Logs 下拉菜单中选择日志记录级别：

    • 关闭：API Gateway 不记录此阶段的请求。

    • 仅限错误：API Gateway 仅记录错误。

    • 错误和信息日志：API Gateway 记录所有事件。

  7. （可选）选择数据跟踪以记录完整的请求和响应数据。这可能会导致记录敏感数据。

    注意

    建议不要为生产 API 启用数据跟踪。

  8. （可选）选择详细指标来开启详细的 CloudWatch 指标。有关更多信息，请参阅 使用 Amazon CloudWatch 指标监控 REST API 执行。

  9. 选择保存更改。

更新阶段设置时，您无需重新部署 API。

启用执行日志记录（CloudFormation）

使用阶段资源上的 MethodSettings 属性来启用执行日志记录。

  TestStage:
    Type: AWS::ApiGateway::Stage
    Properties:
      StageName: test
      RestApiId: !Ref MyAPI
      DeploymentId: !Ref Deployment
      MethodSettings:
        - ResourcePath: "/*"
          HttpMethod: "*"
          LoggingLevel: INFO

要启用 CloudWatch Logs，您必须向 API Gateway 授予权限，才能针对您的账户读取日志和将日志写入到 CloudWatch。要了解更多信息，请参阅《AWS CloudFormation 用户指南》中的将账户与 IAM 角色关联。

执行日志的 Amazon CloudWatch Logs 传输

Amazon CloudWatch Logs 传输为执行日志提供了另一种路径。您无需写入由 API Gateway 管理的日志组，而是配置一个传输，用于将执行日志发送到您拥有和控制的目标。

使用 Amazon CloudWatch Logs 传输：

  • 日志事件最大可达 1 MB，能够捕获更完整的请求和响应数据。超过 1 MB 的有效载荷仍会被截断。

  • 您可以选择目标：您自己的 CloudWatch Logs 日志组、Amazon S3 存储桶或 Firehose 流。

  • 您可以将日志同时发送到多个目标。

  • 您可以控制日志组配置，包括命名和保留。

重要

CloudWatch Logs 传输取代了标准执行日志记录。配置传输时，API Gateway 会停止写入自动管理的日志组。不能对同一个阶段同时使用这两条路径。

创建传输时，API Gateway 将执行日志路由到您配置的目标，而不是自动管理的日志组。删除传输后，执行日志会自动恢复流向自动管理的日志组。除了将 loggingLevel 设置为 ERROR 或 INFO 这一先决条件外，无需对 API Gateway 进行任何其它配置更改。

注意

日志传输是尽力而为的。在极少数情况下，可能会无法传输某些日志事件。

警告

在启用日志传输之前，请更新所有引用自动管理的日志组 (API-Gateway-Execution-Logs_{rest-api-id}/{stage_name}) 的控制面板、警报或订阅筛选条件。传输处于活动状态后，该日志组不再接收新事件。

下表对标准执行日志记录与 Amazon CloudWatch Logs 传输进行了比较。

标准执行日志记录 Amazon CloudWatch Logs 传输
最大日志事件大小 1KB 1 MB
目标 CloudWatch Logs（托管式日志组） CloudWatch Logs、Amazon S3、Firehose（您自己的资源）
多个目标 否 是
日志组名称 由 API Gateway 固定 由您选择
设置 启用日志记录时自动执行 需要创建 Amazon CloudWatch Logs 传输
先决条件 将 loggingLevel 设置为 ERROR 或 INFO 将 loggingLevel 设置为 ERROR 或 INFO
注意

如果在配置传输后将 loggingLevel 设置为 OFF，则不会生成或传输任何执行日志。您的传输目标仍处于已配置状态，但不会接收任何数据。

要创建传输，请参阅为 REST API 执行日志创建日志传输。