API Gateway で WebSocket API のログ記録を設定する - Amazon API Gateway

API Gateway で WebSocket API のログ記録を設定する

ログ記録を有効にして CloudWatch Logs にログを記録することができます。CloudWatch による API のログには、実行ログとアクセスログの 2 種類があります。実行ログでは、API Gateway によって CloudWatch Logs が管理されます。このプロセスには、ロググループとログストリームの作成、および呼び出し元のリクエストとレスポンスのログストリームへのレポートが含まれます。

アクセスログの作成では、API デベロッパーとして、API にアクセスしたユーザーと、呼び出し元が API にアクセスした方法を記録します。独自のロググループを作成したり、既存のロググループを選択したりすることができます。これらは、API Gateway で管理することができます。アクセスの詳細を指定するには、$context 変数 (選択した形式で表示される) を選択し、ロググループを宛先として選択します。

CloudWatch ログ記録の設定方法については、「API Gateway コンソールを使用した CloudWatch による API のログの設定」を参照してください。

[ログの形式] を指定する際に、記録するコンテキスト変数を選択できます。次の変数は、サポートされています。

パラメータ 説明
$context.apiId

API Gateway が API に割り当てる識別子。
$context.authorize.error 認可エラーメッセージ。
$context.authorize.latency 認可レイテンシー (ミリ秒単位)。
$context.authorize.status 認可の試行から返されたステータスコード。
$context.authorizer.error オーソライザーから返されたエラーメッセージ。
$context.authorizer.integrationLatency Lambda オーソライザーレイテンシー (ミリ秒)。
$context.authorizer.integrationStatus オーソライザーから返されたステータスコード。
$context.authorizer.latency オーソライザーのレイテンシー (ミリ秒単位)。
$context.authorizer.requestId AWS エンドポイントのリクエスト ID。
$context.authorizer.status オーソライザーから返されたステータスコード。
$context.authorizer.principalId

クライアントにより送信され、API Gateway Lambda オーソライザー Lambda 関数から返されたトークンと関連付けられたプリンシパルユーザー ID (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

エポック形式の接続時間。
$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 リクエストに関連付けられた API キー ID。
$context.identity.caller

リクエストに署名した発信者のプリンシパル ID。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 認証プロバイダーについては、「Amazon Cognito 開発者ガイド」の「フェデレーティッド ID の使用」を参照してください。
$context.identity.cognitoAuthenticationType

リクエストを行う発信者の Amazon Cognito 認証タイプ。リクエストが Amazon Cognito 認証情報で署名されている場合にのみ使用できます。有効な値は、認証されたアイデンティティauthenticatedおよび認証されていないアイデンティティunauthenticatedです。
$context.identity.cognitoIdentityId

リクエストを行う発信者の Amazon Cognito ID。リクエストが Amazon Cognito 認証情報で署名されている場合にのみ使用できます。
$context.identity.cognitoIdentityPoolId

リクエストを行う発信者の Amazon Cognito ID プール 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 プロキシ統合の場合、バックエンドの Lambda 関数コードからではなく、AWS 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 エポック形式のリクエスト時間 (ミリ秒単位)。
$context.routeKey

選択されたルートキー。
$context.stage

API 呼び出しのデプロイステージ (Beta、Prod など) 。
$context.status

レスポンスステータス。
$context.waf.error から返されたエラーメッセージAWS WAF
$context.waf.latency AWS WAF レイテンシー (ミリ秒単位)。
$context.waf.status から返されたステータスコードAWS WAF

API Gateway コンソールには、一般的に使用されるアクセスログの形式の例が表示されます。以下にもその例を示します。

  • CLF (Common Log Format):

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

    継続文字 (\) は、視覚補助を目的としたものです。ログ形式は 1 行である必要があります。ログ形式の末尾に改行文字 (\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"
}

    継続文字 (\) は、視覚補助を目的としたものです。ログ形式は 1 行である必要があります。ログ形式の末尾に改行文字 (\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>

    継続文字 (\) は、視覚補助を目的としたものです。ログ形式は 1 行である必要があります。ログ形式の末尾に改行文字 (\n) を追加して、各ログエントリの末尾に改行を含めることができます。

  • CSV (カンマ区切り値):

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

    継続文字 (\) は、視覚補助を目的としたものです。ログ形式は 1 行である必要があります。ログ形式の末尾に改行文字 (\n) を追加して、各ログエントリの末尾に改行を含めることができます。