为 API Gateway 中的 REST API 设置 CloudWatch 日志记录
为了帮助调试与请求执行或客户端对 API 的访问的相关问题,您可以启用 Amazon CloudWatch Logs 以记录 API 调用。有关 CloudWatch 的更多信息,请参阅使用 Amazon CloudWatch 指标监控 REST API 执行。
用于 API Gateway 的 CloudWatch 日志格式
在 CloudWatch 中有两种类型的 API 日志记录:执行日志记录和访问日志记录。在执行日志记录中,API Gateway 管理 CloudWatch Logs。该过程包括创建日志组和日志流,以及向日志流报告任意调用方的请求和响应。
记录的数据包括错误或执行跟踪(例如,请求或响应的参数值或负载)、Lambda 授权方(以前称为自定义授权方)使用的数据、是否需要 API 密钥、是否启用了使用计划以及其它信息。API Gateway 会从记录的数据中删除授权标头、API 密钥值和类似的敏感请求参数。
部署 API 时,API Gateway 创建日志组和日志组下的日志流。日志组以 API-Gateway-Execution-Logs_{rest-api-id}/{stage_name}
格式命名。在每个日志组内,日志进一步划分到日志流中,后者在报告记录的数据时按照上次事件时间排序。
在访问日志记录中,作为 API 开发人员,您想要记录谁访问了您的 API 以及调用方访问 API 的方式。您可以创建自己的日志组,或者选择可由 API Gateway 管理的现有日志组。要指定访问详细信息,可以选择 $context 变量、日志格式和日志组目标。
访问日志格式必须至少包括 $context.requestId
或 $context.extendedRequestId
。作为最佳实践,请在日志格式中包含 $context.requestId
和 $context.extendedRequestId
。
$context.requestId
-
这会将值记录在
x-amzn-RequestId
标头中。客户端可以用通用唯一标识符 (UUID) 格式的值覆盖x-amzn-RequestId
标头中的值。API Gateway 返回x-amzn-RequestId
响应标头中的此请求 ID。API Gateway 将不采用 UUID 格式的被覆盖的请求 ID 替换为访问日志中的
。UUID
_REPLACED_INVALID_REQUEST_ID $context.extendedRequestId
-
extendedRequestID 是 API Gateway 生成的唯一 ID。API Gateway 返回
x-amz-apigw-id
响应标头中的此请求 ID。API 调用者无法提供或覆盖此请求 ID。您可能需要向 AWS Support 提供此值,来协助排查 API 的问题。有关更多信息,请参阅 适用于数据模型、授权方、映射模板和 CloudWatch 访问日志记录的 $context 变量。
注意
仅支持 $context
变量。
选择您的分析后端也采用的日志格式,例如常用日志格式
一些常用访问日志格式的示例在 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 $context.extendedRequestId
-
JSON
:{ "requestId":"$context.requestId", "extendedRequestId":"$context.extendedRequestId","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"> <extendedRequestId>$context.extendedRequestId</extendedRequestId> <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,$context.extendedRequestId
CloudWatch 日志记录的权限
要启用 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": "*" } ] }
注意
API Gateway 将调用 AWS Security Token Service 以恢复 IAM 角色,因此请确保已为区域启用 AWS STS。有关更多信息,请参阅在AWS区域中管理AWS STS。
要将这些权限授予您的账户,请使用 apigateway.amazonaws.com
作为其可信实体创建一个 IAM 角色,将之前的策略附加到此 IAM 角色,然后在您账户的 cloudWatchRoleArn 属性上设置 IAM 角色 ARN。您必须为要在其中启用 CloudWatch Logs 的每个AWS区域单独设置 cloudWatchRoleArn 属性。
如果您在设置 IAM 角色 ARN 时收到错误,请检查您的 AWS Security Token Service 账户设置,以确保在您所使用的区域中启用了 AWS STS。有关启用 AWS STS 的更多信息,请参阅 IAM 用户指南中的在AWS区域中管理AWS STS。
使用 API Gateway 控制台设置 CloudWatch API 日志记录
要设置 CloudWatch API 日志记录,您必须已经将 API 部署到某个阶段。您还必须已经为账户配置了合适的 CloudWatch Logs 角色 ARN。
通过以下网址登录到 Amazon API Gateway 控制台:https://console.aws.amazon.com/apigateway
。 -
在主导航窗格上选择设置,然后在日志记录下选择编辑。
-
对于 CloudWatch 日志角色 ARN,输入具有相应权限的 IAM 角色的 ARN。对于每个使用 API Gateway 创建 API 的 AWS 账户,您都需要执行一次此操作。
-
在主导航窗格中,选择 API,然后执行以下操作之一:
-
选择现有 API,然后选择一个阶段。
-
创建 API,然后将其部署到阶段。
-
在主导航窗格中,选择阶段。
-
在日志和跟踪部分中,选择编辑。
-
启用执行日志记录:
-
从 CloudWatch Logs 下拉菜单中选择日志记录级别。日志记录级别如下所示:
-
关闭 - 不对此阶段开启日志记录。
-
仅限错误 - 仅对错误启用日志记录。
-
错误和信息日志 - 对所有事件启用日志记录。
完整的请求和响应日志 - 对所有事件启用详细日志记录。这对于排除 API 故障非常有用,但可能会导致记录敏感数据。
注意
我们建议不要为生产 API 使用完整请求和响应日志。
-
-
如果需要,请选择详细指标以开启详细的 CloudWatch 指标。
有关 CloudWatch 指标的更多信息,请参阅使用 Amazon CloudWatch 指标监控 REST API 执行。
-
-
启用访问日志记录:
-
开启自定义访问日志记录。
-
对于访问日志目标 ARN,输入日志组的 ARN。ARN 格式为
arn:aws:logs:
。{region}
:{account-id}
:log-group:log-group-name
-
对于日志格式,输入日志格式。您可以选择 CLF、JSON、XML 或 CSV。要了解有关示例日志格式的更多信息,请参阅用于 API Gateway 的 CloudWatch 日志格式。
-
-
选择保存更改。
注意
您可以分别启用执行日志记录和访问日志记录,这两者相互独立。
API Gateway 现已准备好记录对您 API 的请求。在更新阶段设置、日志或阶段变量时,您无需重新部署 API。
使用 AWS CloudFormation 设置 CloudWatch API 日志记录
使用以下示例 AWS CloudFormation 模板创建 Amazon CloudWatch Logs 日志组并配置阶段的执行和访问日志记录。要启用 CloudWatch Logs,您必须向 API Gateway 授予权限,才能针对您的账户读取日志和将日志写入到 CloudWatch。要了解更多信息,请参阅《AWS CloudFormation 用户指南》中的将账户与 IAM 角色关联。
TestStage: Type: AWS::ApiGateway::Stage Properties: StageName: test RestApiId: !Ref MyAPI DeploymentId: !Ref Deployment Description: "test stage description" MethodSettings: - ResourcePath: "/*" HttpMethod: "*" LoggingLevel: INFO AccessLogSetting: DestinationArn: !GetAtt MyLogGroup.Arn Format: $context.extendedRequestId $context.identity.sourceIp $context.identity.caller $context.identity.user [$context.requestTime] "$context.httpMethod $context.resourcePath $context.protocol" $context.status $context.responseLength $context.requestId MyLogGroup: Type: AWS::Logs::LogGroup Properties: LogGroupName: !Join - '-' - - !Ref MyAPI - access-logs