API Gateway での CloudWatch による REST API のログの設定 - Amazon API Gateway

API Gateway での CloudWatch による REST API のログの設定

リクエストの実行や API へのクライアントのアクセスに関連する問題のデバッグに役立てるために、Amazon CloudWatch Logs で API コールのログを有効にすることができます。CloudWatch の詳細については、「Amazon CloudWatch のメトリクスを使用した REST 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 など、分析バックエンドでも採用されているログ形式を選択します。その後、フィードに直接アクセスログを入力して、メトリクスを計算してレンダリングすることができます。ログの形式を定義するには、ロググループの ARN をステージaccessLogSettings/destinationArn プロパティに設定します。ロググループの 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

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

  • 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" \ }

    継続文字 (\) は、視覚補助を目的としたものです。ログ形式は 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> \ <httpMethod>$context.httpMethod</httpMethod> \ <resourcePath>$context.resourcePath</resourcePath> \ <status>$context.status</status> \ <protocol>$context.protocol</protocol> \ <responseLength>$context.responseLength</responseLength> \ </request>

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

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

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

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

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

これらのアクセス許可をアカウントに付与するには、apigateway.amazonaws.com を信頼できるエンティティとして IAM ロールを作成し、前述のポリシーを IAM ロールにアタッチして、その IAM ロールの ARN をアカウントcloudWatchRoleArn プロパティに設定します。cloudWatchRoleArn プロパティは、CloudWatch Logs を有効にする AWS リージョンごとに設定する必要があります。

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. API Gateway コンソール https://console.aws.amazon.com/apigateway にサインインします。

  2. REST API を選択します。

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

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

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

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

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

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

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

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

    3. 必要に応じて、[Log full requests/responses data (完全なリクエスト/レスポンスデータをログに記録する)] を選択して、完全な API リクエストとレスポンスがログに記録されるようにします。

      警告

      このログは API のトラブルシューティングに役立ちますが、機密データが記録される可能性があります。本番稼働用 API では Log full requests/responses data を有効にしないことをお勧めします。

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

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

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

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

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

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

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

注記

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

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