为 API Gateway 中的 WebSocket API 配置日志记录 - Amazon API Gateway

为 API Gateway 中的 WebSocket API 配置日志记录

您可以启用日志记录以将日志写入 CloudWatch Logs。在 CloudWatch 中有两种类型的 API 日志记录：执行日志记录和访问日志记录。在执行日志记录中，API Gateway 管理 CloudWatch Logs。该过程包括创建日志组和日志流，以及向日志流报告任意调用方的请求和响应。

在访问日志记录中，作为 API 开发人员，您想要记录谁访问了您的 API 以及调用方访问 API 的方式。您可以创建自己的日志组，或者选择可由 API Gateway 管理的现有日志组。要指定访问详细信息，您可以选择 $context 变量（以您选择的格式表示），并选择日志组作为目标。

有关如何设置 CloudWatch 日志记录的说明，请参阅使用 API Gateway 控制台设置 CloudWatch API 日志记录。

当您指定 Log Format (日志格式) 时，您可以选择要记录的上下文变量。支持以下变量。

参数 说明
$context.apiId

API Gateway 分配给您的 API 的标识符。
$context.authorize.error 授权错误消息。
$context.authorize.latency 授权延迟时间（以毫秒为单位）。
$context.authorize.status 从授权尝试返回的状态代码。
$context.authorizer.error 从授权方返回的错误消息。
$context.authorizer.integrationLatency Lambda 授权方延迟（以毫秒为单位）。
$context.authorizer.integrationStatus 从 Lambda 授权方返回的状态代码。
$context.authorizer.latency 授权方延迟（以毫秒为单位）。
$context.authorizer.requestId AWS 端点的请求 ID。
$context.authorizer.status 从授权方返回的状态代码。
$context.authorizer.principalId

与由客户端发送的令牌相关联的委托人用户标识，从API Gateway Lambda 授权方 Lambda 函数返回。（Lambda 授权方以前称为自定义授权方。）
$context.authorizer.property

从 API Gateway Lambda 授权方函数返回的 context 映射的指定键/值对的字符串化值。例如，如果授权方返回以下 context 映射：

"context" : {
                            "key": "value",
                            "numKey": 1,
                            "boolKey": true
                            }

调用 $context.authorizer.key 将返回 "value" 字符串，调用 $context.authorizer.numKey 将返回 "1" 字符串，而调用 $context.authorizer.boolKey 将返回 "true" 字符串。
$context.authenticate.error 从身份验证尝试返回的错误消息。
$context.authenticate.latency 身份验证延迟时间（以毫秒为单位）。
$context.authenticate.status 从身份验证尝试返回的状态代码。
$context.connectedAt

Epoch 格式的连接时间。
$context.connectionId

连接的唯一 ID，可用于对客户端进行回调。
$context.domainName

WebSocket API 的域名。这可用于对客户端进行回调（而不是硬编码值）。
$context.error.message

包含 API Gateway 错误消息的字符串。
$context.error.messageString $context.error.message 的带引号的值，即 "$context.error.message"。
$context.error.responseType

错误响应类型。
$context.error.validationErrorString

包含详细验证错误消息的字符串。
$context.eventType

事件类型：CONNECT、MESSAGE 或 DISCONNECT。
$context.extendedRequestId 等效于 $context.requestId。
$context.identity.accountId

与请求关联的 AWS 账户 ID。
$context.identity.apiKey

API 所有者密钥与启用密钥的 API 请求关联。
$context.identity.apiKeyId API 密钥 ID 与启用密钥的 API 请求关联
$context.identity.caller

签发请求的调用方的委托人标识符。对于使用 IAM 授权的路由支持此项。
$context.identity.cognitoAuthenticationProvider

发出请求的调用方使用的所有 Amazon Cognito 身份验证提供商的逗号分隔列表。仅当使用 Amazon Cognito 凭证对请求签名时才可用。

例如，对于 Amazon Cognito 身份池中的身份，cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim

有关更多信息，请参阅 Amazon Cognito 开发人员指南 中的使用联合身份。
$context.identity.cognitoAuthenticationType

发出请求的调用方的 Amazon Cognito 身份验证类型。仅当使用 Amazon Cognito 凭证对请求签名时才可用。可能的值包括经过身份验证的身份的 authenticated 和未经身份验证的身份的 unauthenticated。
$context.identity.cognitoIdentityId

发出请求的调用方的 Amazon Cognito 身份 ID。仅当使用 Amazon Cognito 凭证对请求签名时才可用。
$context.identity.cognitoIdentityPoolId

发出请求的调用方的 Amazon Cognito 身份池 ID。仅当使用 Amazon Cognito 凭证对请求签名时才可用。
$context.identity.principalOrgId

AWS 组织 ID。对于使用 IAM 授权的路由支持此项。
$context.identity.sourceIp

向 API Gateway 发出请求的 TCP 连接的源 IP 地址。
$context.identity.user

将获得资源访问权限授权的用户的委托人标识符。对于使用 IAM 授权的路由支持此项。
$context.identity.userAgent

API 调用方的用户代理。
$context.identity.userArn

身份验证后标识的有效用户的 Amazon 资源名称 (ARN)。
$context.integration.error 从集成返回的错误消息。
$context.integration.integrationStatus 对于 Lambda 代理集成，从 AWS Lambda（而不是从后端 Lambda 函数代码）返回的状态代码。
$context.integration.latency 集成延迟（毫秒）。等效于 $context.integrationLatency。
$context.integration.requestId AWS 端点的请求 ID。等效于 $context.awsEndpointRequestId。
$context.integration.status 从集成返回的状态代码。对于 Lambda 代理集成，这是 Lambda 函数代码返回的状态代码。等效于 $context.integrationStatus。
$context.integrationLatency 集成延迟（毫秒），仅可用于访问日志记录。
$context.messageId

消息的唯一服务器端 ID。仅当 $context.eventType 为 MESSAGE 时才可用。
$context.requestId

与 $context.extendedRequestId 相同。
$context.requestTime CLF 格式的请求时间 (dd/MMM/yyyy:HH:mm:ss +-hhmm)。
$context.requestTimeEpoch Epoch 格式的请求时间，以毫秒为单位。
$context.routeKey

选定的路由键。
$context.stage

API 调用的部署阶段（例如测试或生产）。
$context.status

响应状态。
$context.waf.error 从 返回的错误消息AWS WAF
$context.waf.latency AWS WAF 延迟时间（以毫秒为单位）。
$context.waf.status 从 返回的状态代码AWS WAF

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

  • CLF (常用日志格式 )：

    $context.identity.sourceIp $context.identity.caller \
$context.identity.user [$context.requestTime] "$context.eventType $context.routeKey $context.connectionId" \
$context.status $context.requestId

    继续符 (\) 用作视觉辅助。日志格式必须为单行。您可以在日志格式末尾添加换行符 (\n)，以便在每个日志条目末尾添加换行符。

  • JSON: 

    {
"requestId":"$context.requestId", \
"ip": "$context.identity.sourceIp", \
"caller":"$context.identity.caller", \
"user":"$context.identity.user", \
"requestTime":"$context.requestTime", \
"eventType":"$context.eventType", \
"routeKey":"$context.routeKey", \
"status":"$context.status", \
"connectionId":"$context.connectionId"
}

    继续符 (\) 用作视觉辅助。日志格式必须为单行。您可以在日志格式末尾添加换行符 (\n)，以便在每个日志条目末尾添加换行符。

  • XML: 

    <request id="$context.requestId"> \
 <ip>$context.identity.sourceIp</ip> \
 <caller>$context.identity.caller</caller> \
 <user>$context.identity.user</user> \
 <requestTime>$context.requestTime</requestTime> \
 <eventType>$context.eventType</eventType> \
 <routeKey>$context.routeKey</routeKey> \
 <status>$context.status</status> \
 <connectionId>$context.connectionId</connectionId> \
</request>

    继续符 (\) 用作视觉辅助。日志格式必须为单行。您可以在日志格式末尾添加换行符 (\n)，以便在每个日志条目末尾添加换行符。

  • CSV (逗号分隔值)：

    $context.identity.sourceIp,$context.identity.caller, \
$context.identity.user,$context.requestTime,$context.eventType, \
$context.routeKey,$context.connectionId,$context.status, \
$context.requestId

    继续符 (\) 用作视觉辅助。日志格式必须为单行。您可以在日志格式末尾添加换行符 (\n)，以便在每个日志条目末尾添加换行符。