API Gateway での CloudWatch によるログの形式 CloudWatch によるログのアクセス許可 API Gateway コンソールを使用した CloudWatch による API のログの設定 AWS CloudFormation を使用した CloudWatch API ログ記録の設定

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

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

API Gateway での CloudWatch によるログの形式

CloudWatch による API のログには、実行ログとアクセスログの 2 種類があります。実行ログでは、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 ヘッダーに値が記録されます。クライアントは、x-amzn-RequestId ヘッダーの値を共通の一意の識別子 (UUID) 形式の値で上書きできます。API Gateway は、x-amzn-RequestId レスポンスヘッダー内のこのリクエスト ID を返します。API Gateway は、アクセスログの上書きされたリクエスト ID のうち UUID の形式ではないものを UUID_REPLACED_INVALID_REQUEST_ID に置き換えます。
$context.extendedRequestId: extendedRequestID は、API Gateway が生成する一意の ID です。API Gateway は、x-amz-apigw-id レスポンスヘッダー内のこのリクエスト ID を返します。API 発信者は、このリクエスト ID を提供することやオーバーライドすることはできません。API のトラブルシューティング役立てるために、必要に応じて、この値を AWS サポートに提供します。詳細については、「データモデル、オーソライザー、マッピングテンプレート、および CloudWatch アクセスログ記録用の $context 変数」を参照してください。

注記

$context 変数のみがサポートされます。

Common Log Format (CLF)、JSON、XML、CSV など、分析バックエンドでも採用されているログ形式を選択します。その後、フィードに直接アクセスログを入力して、メトリクスを計算してレンダリングすることができます。ログの形式を定義するには、ロググループの ARN をステージの accessLogSettings/destinationArn プロパティに設定します。ロググループの ARN は、CloudWatch コンソールで取得できます。アクセスログの形式を定義するには、選択した形式をステージの 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 $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 は 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 を設定しておく必要があります。

https://console.aws.amazon.com/apigateway で API Gateway コンソールにサインインします。
メインナビゲーションペインで [設定] を選択し、[ログ] で [編集] を選択します。
[CloudWatch ログのロール ARN] に、適切な権限を持つ IAM ロールの ARN を入力します。API Gateway を使用して API を作成する AWS アカウントごとにこれを実行する必要があります。
メインナビゲーションペインで、[API] を選択して、以下のいずれかを実行します。
1. 既存の API を選択し、ステージを選択します。
2. API を作成してから、ステージにデプロイします。
メインナビゲーションペインで、[ステージ] を選択します。
[ログおよびトレース] セクションで [編集] を選択します。
実行ログ作成を有効にするには
1. [CloudWatch Logs] ドロップダウンメニューからログ記録レベルを選択します。ログ記録レベルは、以下のとおりです。
  - オフ — この段階ではログ記録はオンになっていません。
  - エラーのみ — ログ記録はエラーに対してのみ有効になっています。
  - エラーと情報ログ — ログ記録はすべてのイベントに対して有効になっています。
2. (オプション) [データトレース] を選択して、ステージのデータトレースログ記録を有効にします。このログは API のトラブルシューティングに役立ちますが、機密データが記録される可能性があります。
  
  注記
  本番稼働用 API では [データトレース] を有効にしないことをお勧めします。
3. (オプション) [詳細メトリクス] を選択して、詳細な CloudWatch メトリクスを有効にします。
CloudWatch のメトリクスの詳細については、「Amazon CloudWatch のメトリクスを使用して REST API の実行をモニタリングする」を参照してください。
アクセスログの作成を有効にするには
1. [カスタムアクセスロギング] を有効にします。
2. [アクセスログの送信先 ARN] に、ロググループの ARNを入力します。ARN 形式は arn:aws:logs:{region}:{account-id}:log-group:log-group-name です。
3. [ログの形式] にログの形式を入力します。[CLF]、[JSON]、[XML]、または [CSV] を選択できます。ログ形式の例について詳しくは、「API Gateway での CloudWatch によるログの形式」を参照してください。
[Save changes] (変更の保存) をクリックします。

注記

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

これで、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

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

AWS の API Gateway 用モニタリングツール

Firehose