Amazon API Gateway
開発者ガイド

API Gateway CloudWatch の API ログ作成をセットアップする

リクエストの実行や API へのクライアントアクセスに関連する問題のデバッグに役立つ Amazon CloudWatch Logs を有効にして、API コールを記録できます。CloudWatch の詳細については、「Amazon CloudWatch を使用した API 実行のモニタリング」を参照してください。

API Gateway での CloudWatch のログ形式

CloudWatch での API ログ作成には実行ログ作成とアクセスログ作成の 2 つのタイプがあります。実行ログ作成では、API Gateway は CloudWatch Logs を管理します。このプロセスには、ロググループとログストリームの作成、および呼び出し元のリクエストとレスポンスのログストリームへのレポートが含まれます。記録されたデータには、エラーまたは実行の追跡 (リクエストまたはレスポンスパラメータ値またはペイロードなど)、Lambda オーソライザー (以前のカスタムオーソライザー) が使用するデータ、API キーが必要かどうか、使用量プランが有効かどうかなどの情報が含まれます。

API をデプロイすると、API Gateway はそのロググループの下にロググループとログストリームを作成します。ロググループの名前は API-Gateway-Execution-Logs_{rest-api-id}/{stage_name} 形式に従います。各ロググループ内で、ログはログデータにさらに分割され、ログデータがレポートされるときに [最終のイベント時刻] によって順序付けられます。

アクセスログの作成では、API 開発者として、API にアクセスしたユーザーと、呼び出し元が API にアクセスした方法を記録します。独自のロググループを作成したり、既存のロググループを選択したりすることができます。これらは、API Gateway で管理することができます。アクセスの詳細を指定するには、$context 変数を選択し、選択した形式で表示し、ロググループを宛先として選択します。各ログの一意性を維持するために、アクセスログ形式に $context.requestId を含める必要があります。

注記

$context 変数のみがサポートされ、$input などはサポートされません。

Common Log Format (CLF)、JSON、XML、CSV など、分析バックエンドでも採用されているログ形式を選択します。その後、フィードに直接アクセスログを入力して、メトリクスを計算してレンダリングすることができます。ログ形式を定義するには、ステージaccessLogSettings/destinationArn プロパティでロググループ ARN を設定します。[ARN] 列が表示用に選択されている場合は、CloudWatch コンソールでロググループ ARN を取得できます。アクセスログフォーマットを定義するには、ステージ上の accessLogSetting/format プロパティで選択したフォーマットを設定します。

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

  • CLF (Common Log Format):

    $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 ログ記録のアクセス許可

CloudWatch Logs を有効にするには、アカウントで CloudWatch に API Gateway のログを読み書きするための適切なアクセス許可を付与する必要があります。この 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": "*" } ] }

注記

IAM ロールを引き受けるために API Gateway が AWS Security Token Service を呼び出すため、リージョンで AWS STS が有効になっていることを確認します。詳細については、「AWS リージョンでの AWS STS の管理」を参照してください。

これらのアクセス許可をアカウントに付与するには、apigateway.amazonaws.com を信頼できるエンティティとして使用して IAM ロールを作成し、前述のポリシーを IAM ロールに添付し、アカウントcloudWatchRoleArn プロパティに IAM ロール ARN を設定します。

IAM ロール ARN を設定するときにエラーが発生した場合は、AWS Security Token Service アカウントの設定を確認し、使用しているリージョンで AWS STS が有効になっていることを確認してください。AWS STS を有効にする方法の詳細については、IAM ユーザーガイドの「AWS リージョンでの AWS STS の管理」を参照してください。

API Gateway コンソールを使用して CloudWatch API ログ作成をセットアップする

CloudWatch API ログ記録をセットアップするには、API をステージにデプロイしておく必要があります。また、アカウントに適切な CloudWatch Logs ロール ARN を設定する必要があります。

  1. https://console.aws.amazon.com/apigateway で API Gateway コンソールにサインインします。

  2. プライマリナビゲーションパネルから [Settings (設定)] を選択し、[CloudWatch log role ARN (CloudWatch ログのロール ARN)] で適切なアクセス許可を持つ IAM ロールの ARN を入力します。これは一度行う必要があります。

  3. 以下のいずれかの操作を行います。

    1. 既存の API を選択し、ステージを選択します。

    2. API を作成し、ステージにデプロイします。

  4. [ステージエディタ] で [ログ/トレース] を選択します。

  5. 実行ログ作成を有効にするには

    1. [CloudWatch 設定] で [CloudWatch ログの有効化] を選択します。

    2. ドロップダウンメニューから [エラー] または [情報] を選択します。

    3. 必要に応じて、[詳細 CloudWatch メトリクスを有効化] を選択します。

    CloudWatch メトリクスの詳細については、「Amazon CloudWatch を使用した API 実行のモニタリング」を参照してください。

  6. アクセスログの作成を有効にするには

    1. [カスタムアクセスのログ記録] の [アクセスログの作成の有効化] を選択します。

    2. [Access Log Destination ARN (アクセスログの送信先 ARN)] にロググループの ARNを入力します。ARN 形式は arn:aws:logs:{region}:{account-id}:log-group:API-Gateway-Execution-Logs_{rest-api-id}/{stage-name} です。

    3. [ログの形式] にログの形式を入力します。[CLF]、[JSON]、[XML]、[CSV] を選択して、提供された例の 1 つをガイドとして使用できます。

  7. [Save Changes (変更の保存)] を選択します。

注記

実行ログとアクセスログを互いに独立して有効にすることができます。

API Gateway が API にリクエストのログを作成する準備が整いました。ステージ設定、ログ、またはステージ変数を更新するときに API を再デプロイする必要はありません。