Amazon API Gateway
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 Amazon AWS 入门

在 API Gateway 中设置 API 日志记录

为了帮助调试与请求执行或客户端对您 API 访问的相关问题,您可以启用 Amazon CloudWatch Logs 跟踪 API 调用。在启用之后,API Gateway 将在 CloudWatch 中记录 API 调用。有两种类型的 API 日志记录:执行日志记录和访问日志记录。

在执行日志记录中,API Gateway 管理 CloudWatch Logs。该过程包括创建日志组和日志流,以及向日志流报告任意调用方的请求和响应。记录的数据包括错误或执行跟踪 (例如请求或响应的参数值或负载)、自定义授权方使用的数据、是否需要 API 密钥、是否启用了使用计划等等。

部署 API 时,API Gateway 创建日志组和日志组下的日志流。日志组以 API-Gateway-Execution-Logs_{rest-api-id}/{stage_name} 格式命名。在每个日志组内,日志进一步划分到日志流中,后者在报告记录的数据时按照 Last Event Time 排序。

在访问日志记录中,作为 API 开发人员,您想要记录谁访问了您的 API 以及调用方访问 API 的方式。您可以创建自己的日志组或者选择可由 API Gateway 管理的现有日志组。您可以通过选择 $context 变量指定访问详细信息,以您选择的格式表示,并选择日志组作为目标。为保留各个日志的唯一性,访问日志格式必须包括 $context.requestId

选择您的分析后端也采用的日志格式,例如常用日志格式 (CLF)、JSON、XML 或 CSV。然后,您可以将访问日志直接输送到其中,以计算和呈现您的指标。要定义日志格式,请在阶段accessLogSettings/destinationArn 属性上设置日志组 ARN。您可以在 CloudWatch 控制台中获取日志组 ARN,前提是选择了要显示的 ARN 列。要定义访问日志格式,请在阶段accessLogSetting/format 属性上设置选定格式。

一些常用访问日志格式的示例在 API Gateway 控制台中显示,下面列出了这些格式。

  • CLF (常用日志格式 ):

    $context.identity.sourceIp $context.identity.caller \ $context.identity.user [$context.requestTime] \ "$context.httpMethod $context.resourcePath $context.protocol" \ $context.status $context.responseLength $context.requestId

    继续符 (\) 用作视觉辅助,日志格式不能有任何换行符。

  • JSON

    { "requestId":"$context.requestId", \ "ip": "$context.identity.sourceIp", \ "caller":"$context.identity.caller", \ "user":"$context.identity.user", \ "requestTime":"$context.requestTime", \ "httpMethod":"$context.httpMethod", \ "resourcePath":"$context.resourcePath", \ "status":"$context.status", \ "protocol":"$context.protocol", \ "responseLength":"$context.responseLength" \ }

    继续符 (\) 用作视觉辅助,日志格式不能有任何换行符。

  • XML

    <request id="$context.requestId"> \ <ip>$context.identity.sourceIp</ip> \ <caller>$context.identity.caller</caller> \ <user>$context.identity.user</user> \ <requestTime>$context.requestTime</requestTime> \ <httpMethod>$context.httpMethod</httpMethod> \ <resourcePath>$context.resourcePath</resourcePath> \ <status>$context.status</status> \ <protocol>$context.protocol</protocol> \ <responseLength>$context.responseLength</responseLength> \ </request>

    继续符 (\) 用作视觉辅助,日志格式不能有任何换行符。

  • CSV (逗号分隔值):

    $context.identity.sourceIp,$context.identity.caller,\ $context.identity.user,$context.requestTime,$context.httpMethod,\ $context.resourcePath,$context.protocol,$context.status,\ $context.responseLength,$context.requestId

    继续符 (\) 用作视觉辅助,日志格式不能有任何换行符。

权限

要启用 CloudWatch Logs,您必须授予 API Gateway 合适的权限,以在您账户的 CloudWatch 中读取和写入日志。AmazonAPIGatewayPushToCloudWatchLogs 托管策略 (ARN 为 arn:aws:iam::aws:policy/service-role/AmazonAPIGatewayPushToCloudWatchLogs) 具有全部必需的权限。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:DescribeLogGroups", "logs:DescribeLogStreams", "logs:PutLogEvents", "logs:GetLogEvents", "logs:FilterLogEvents" ], "Resource": "*" } ] }

要将这些权限授予您的账户,请使用 apigateway.amazonaws.com 作为可信实体创建 IAM 角色,将之前的策略附加到 IAM 角色,然后在您账户cloudWatchRoleArn 属性上设置 IAM 角色 ARN。

使用 API Gateway 控制台设置 API 日志记录

要设置 API 日志记录,您必须已经将 API 部署到某个阶段。您还必须已经为账户配置了合适的 CloudWatch Logs 角色 ARN。

  1. 登录 API Gateway 控制台。

  2. 从主导航面板中选择 Settings。在 CloudWatch log role ARN 中键入具有相应权限的 IAM 角色的 ARN。您需要执行一次此操作。

  3. 执行以下任一操作:

    1. 选择现有 API,然后选择一个阶段。

    2. 创建 API 并将其部署到阶段。

  4. Stage Editor 中选择 Logs

  5. 要启用执行日志记录,请在 CloudWatch Settings 下选择 Enable CloudWatch Logs。从下拉菜单中选择 ErrorInfo。如果需要,请选择 Enable Detailed CloudWatch Metrics

  6. 要启用访问日志记录,请在 Custom Access Logging 下选择 Enable Access Logging。然后在 CloudWatch Group 中键入日志组的 ARN。在 Log Format 中键入日志格式。您可以选择 CLFJSONXMLCSV 以使用提供的示例之一作为指南。

  7. 选择 Save Changes

注意

您可以分别启用执行日志记录和访问日志记录,这两者相互独立。

API Gateway 现已准备好记录对您 API 的请求。在更新阶段设置、日志或阶段变量时,您无需重新部署 API。