# API Gateway で REST API の CloudWatch ログ記録を設定する
<a name="set-up-logging"></a>

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

## API Gateway での CloudWatch によるログの形式
<a name="apigateway-cloudwatch-log-formats"></a>

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

ログに記録されるデータには、エラーや実行のトレース (リクエストやレスポンスのパラメータ値やペイロードなど)、Lambda オーソライザー (旧カスタムオーソライザー) が使用するデータ、API キーが必要かどうか、使用量プランが有効かどうかなどの情報が含まれます。API Gateway は、認可ヘッダー、API キー値、および同様の機密リクエストパラメータをログデータからマスキングします。

セキュリティ体制を向上させるには、`ERROR` または `INFO` レベルで実行ログを使用することをお勧めします。これは、さまざまなコンプライアンスフレームワークに準拠するために必要になる場合があります。詳細については、*AWS Security Hub ユーザーガイド*の「[Amazon API Gateway のコントロール](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html)」を参照してください。

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

アクセスログの作成では、API デベロッパーとして、API にアクセスしたユーザーと、呼び出し元が API にアクセスした方法を記録します。独自のロググループを作成したり、既存のロググループを選択したりすることができます。これらは、API Gateway で管理することができます。アクセスの詳細を指定するには、[`$context`](api-gateway-variables-for-access-logging.md) 変数、ログ形式、ロググループの送信先を選択します。

アクセスログには少なくとも `$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 サポートに提供します。詳細については、「[API Gateway のアクセスのログ記録のための変数](api-gateway-variables-for-access-logging.md)」を参照してください。

[Common Log Format](https://httpd.apache.org/docs/current/logs.html#common) (CLF)、JSON、XML、CSV など、分析バックエンドでも採用されているログ形式を選択します。その後、フィードに直接アクセスログを入力して、メトリクスを計算してレンダリングすることができます。ログの形式を定義するには、ロググループの ARN を[ステージ](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html)の [accessLogSettings/destinationArn](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#destinationArn) プロパティに設定します。ロググループの ARN は、CloudWatch コンソールで取得できます。アクセスログの形式を定義するには、選択した形式を[ステージ](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html)の [accessLogSetting/format](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#format) プロパティに設定します。

API Gateway コンソールには、一般的に使用されるアクセスログの形式の例が表示されます。以下にもその例を示します。
+ `CLF` ([Common Log Format](https://httpd.apache.org/docs/current/logs.html#common)):

  ```
  $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 によるログのアクセス許可
<a name="set-up-access-logging-permissions"></a>

CloudWatch Logs を有効にするには、API Gateway の CloudWatch に対するログの読み取りと書き込みのアクセス許可をアカウントに付与する必要があります。[AmazonAPIGatewayPushToCloudWatchLogs](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAPIGatewayPushToCloudWatchLogs.html) には、必要なすべてのアクセス許可が含まれています。

**注記**  
API Gateway は IAM ロールを引き受けるために AWS Security Token Service を呼び出すため、リージョンで AWS STS が有効になっていることを確認します。詳細については、「[AWS リージョンでの AWS STS の管理](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html)」を参照してください。

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

IAM ロール ARN の設定時にエラーが発生した場合は、AWS Security Token Service アカウントの設定をチェックして、使用しているリージョンで AWS STS が有効になっていることを確認してください。AWS STS を有効にする方法の詳細については、*IAM ユーザーガイド*の「[AWS リージョンでの AWS STS の管理](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html#sts-regions-activate-deactivate)」を参照してください。

## API Gateway コンソールを使用した CloudWatch による API のログの設定
<a name="set-up-access-logging-using-console"></a>

CloudWatch による API のログを設定するには、API をステージにデプロイしておく必要があります。また、アカウントに[適切な CloudWatch Logs ロール](#set-up-access-logging-permissions)の ARN を設定しておく必要があります。

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

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

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

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

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

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

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

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

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

   1. **[CloudWatch Logs]** ドロップダウンメニューからログ記録レベルを選択します。ログ記録レベルは、以下のとおりです。
      + **オフ** — この段階ではログ記録はオンになっていません。
      + **エラーのみ** — ログ記録はエラーに対してのみ有効になっています。
      + **エラーと情報ログ** — ログ記録はすべてのイベントに対して有効になっています。

   1. (オプション) **[データトレース]** を選択して、ステージのデータトレースログ記録を有効にします。このログは API のトラブルシューティングに役立ちますが、機密データが記録される可能性があります。
**注記**  
本番稼働用 API では **[データトレース]** を有効にしないことをお勧めします。

   1. (オプション) **[詳細メトリクス]** を選択して、詳細な CloudWatch メトリクスを有効にします。

   CloudWatch のメトリクスの詳細については、「[Amazon CloudWatch のメトリクスを使用して REST API の実行をモニタリングする](monitoring-cloudwatch.md)」を参照してください。

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

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

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

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

1. **[Save changes]** (変更の保存) をクリックします。

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

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

## CloudFormation を使用した CloudWatch API ログ記録の設定
<a name="set-up-access-logging-using-cloudformation"></a>

次の CloudFormation テンプレート例を使用して Amazon CloudWatch Logs ロググループを作成し、ステージの実行およびアクセスログ記録を設定します。CloudWatch Logs を有効にするには、API Gateway の CloudWatch に対するログの読み取りと書き込みのアクセス許可をアカウントに付与する必要があります。詳細については、**「AWS CloudFormation ガイド」の「[アカウントに IAM ロールを関連付ける](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-account.html#aws-resource-apigateway-account--examples)」を参照してください。

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