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

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

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

注記

$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 $context.extendedRequestId

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

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

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

  • 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>

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

    継続文字 (\) は、視覚補助を目的としたものです。ログ形式は 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. https://console.aws.amazon.com/apigateway で API Gateway コンソールにサインインします。

  2. メインナビゲーションペインで [設定] を選択し、[ログ] で [編集] を選択します。

  3. [CloudWatch ログのロール ARN] に、適切な権限を持つ IAM ロールの ARN を入力します。API Gateway を使用して API を作成する AWS アカウント ごとにこれを実行する必要があります。

  4. メインナビゲーションペインで、[API] を選択して、以下のいずれかを実行します。

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

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

  5. メインナビゲーションペインで、[ステージ] を選択します。

  6. [ログおよびトレース] セクションで [編集] を選択します。

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

    1. [CloudWatch Logs] ドロップダウンメニューからログ記録レベルを選択します。

      警告

      [リクエストとレスポンスの完全なログ] は API のトラブルシューティングに役立ちますが、機密データが記録される可能性があります。本稼働用 API には、[リクエストとレスポンスの完全なログ] を有効にしないことをお勧めします。

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

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

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

    1. [カスタムアクセスロギング] を有効にします。

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

    3. [ログの形式] にログの形式を入力します。[CLF]、[JSON]、[XML]、または [CSV] を選択できます。ログ形式の例について詳しくは、「API Gateway での CloudWatch によるログの形式」を参照してください。

  9. [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