Amazon API Gateway
開発者ガイド

API Gateway での AWS X-Ray のセットアップ

このセクションは、API Gateway で AWS X-Ray をセットアップする方法の詳細情報です。

API Gateway の X-Ray トレースモード

アプリケーションを経由するリクエストのパスは、トレース ID を使用して追跡されます。トレースでは、1 つのリクエスト (通常は HTTP GET または POST リクエスト) で生成されたセグメントをすべて収集します。

API Gateway API のトレースには 2 つのモードがあります。

  • [パッシブ]: API ステージで X-Ray トレースを有効にしていない場合、これがデフォルトの設定です。この手法では、API Gateway API は、アップストリームサービスで X-Ray が有効になっている場合にのみトレースされます。

  • [アクティブ]: API Gateway API ステージにこの設定がある場合、API Gateway は X-Ray によって指定されるサンプリングアルゴリズムに基づいて API コールリクエストを自動的にサンプリングします。

    ステージでアクティブトレースが有効になると、API Gateway は、サービスにリンクされたロールが既にアカウントに存在しない場合、このロールを作成します。このロールは AWSServiceRoleForAPIGateway という名前で、APIGatewayServiceRolePolicy マネージドポリシーがロールにアタッチされます。サービスにリンクされたロールの詳細については、「サービスにリンクされたロールの使用」を参照してください。

    注記

    X-Ray はサンプリングアルゴリズムを適用することで、トレースを効率的にしつつ、API が受け取るリクエストの代表的なサンプルを提供できるようにします。デフォルトのサンプリングアルゴリズムは 1 秒間につき 1 リクエストで、この制限を超えた場合はリクエストの 5 パーセントがサンプリングされます。

API のトレースモードは、API Gateway マネジメントコンソール、API Gateway CLI、または AWS SDK を使用して変更できます。

X-Ray トレースのアクセス許可

ステージで X-Ray トレースを有効にすると、API Gateway は、サービスにリンクされたロールが既にアカウントに存在しない場合、ロールを作成します。このロールは AWSServiceRoleForAPIGateway という名前で、APIGatewayServiceRolePolicy マネージドポリシーがロールにアタッチされます。サービスにリンクされたロールの詳細については、「サービスにリンクされたロールの使用」を参照してください。

API Gateway コンソールで X-Ray トレースを有効にする

Amazon API Gateway コンソールを使用して、API ステージでアクティブトレースを有効にできます。

これらのステップでは、すでに API をステージにデプロイしていることを前提としています。

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

  2. [API] ペインで、API を選択し、[ステージ] を選択します。

  3. [ステージ] ペインで、ステージの名前を選択します。

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

  5. X-Ray トレースを有効にするには、[X-Ray トレース] の下の [X-Ray トレースの有効化] を選択します。

  6. 必要に応じて、[X-Ray サンプリングルールの設定] を選択して X-Ray コンソールに移動し、サンプリングルールを設定します。

API ステージに対して X-Ray を有効にすると、X-Ray マネジメントコンソールを使用してトレースとサービスマップを表示できます。

API Gateway CLI を使用して AWS X-Ray トレースを有効にする

AWS CLI を使用して、ステージの作成時に API ステージに対してアクティブな X-Ray トレースを有効にするには、次の例のように create-stage コマンドを呼び出します。

aws apigateway --endpoint-url {endpoint-url} create-stage \ --rest-api-id {rest-api-id} \ --stage-name {stage-name} \ --deployment-id {deployment-id} \ --region {region} \ --tracing-enabled=true

呼び出しが成功したときの出力例を次に示します。

{ "tracingEnabled": true, "stageName": {stage-name}, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": {deployment-id}, "lastUpdatedDate": 1533849811, "createdDate": 1533849811, "methodSettings": {} }

AWS CLI を使用して、ステージの作成時に API ステージに対してアクティブな X-Ray トレースを無効にするには、次の例のように create-stage コマンドを呼び出します。

aws apigateway --endpoint-url {endpoint-url} create-stage \ --rest-api-id {rest-api-id} \ --stage-name {stage-name} \ --deployment-id {deployment-id} \ --region {region} \ --tracing-enabled=false

呼び出しが成功したときの出力例を次に示します。

{ "tracingEnabled": false, "stageName": {stage-name}, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": {deployment-id}, "lastUpdatedDate": 1533849811, "createdDate": 1533849811, "methodSettings": {} }

AWS CLI を使用して、すでにデプロイされている API に対してアクティブな X-Ray を有効にするには、次のように update-stage コマンドを呼び出します。

aws apigateway update-stage \ --rest-api-id {rest-api-id} \ --stage-name {stage-name} \ --patch-operations op=replace,path=/tracingEnabled,value=true

AWS CLI を使用して、すでにデプロイされている API に対してアクティブな X-Ray を無効にするには、次の例のように update-stage コマンドを呼び出します。

aws apigateway update-stage \ --endpoint-url {endpoint-url} \ --rest-api-id {rest-api-id} \ --stage-name {stage-name} \ --region {region} \ --patch-operations op=replace,path=/tracingEnabled,value=false

呼び出しが成功したときの出力例を次に示します。

{ "tracingEnabled": false, "stageName": {stage-name}, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": {deployment-id}, "lastUpdatedDate": 1533850033, "createdDate": 1533849811, "methodSettings": {} }

API ステージに対して X-Ray を有効したら、X-Ray CLI を使用してトレース情報を取得します。詳細については、「AWS CLI での AWS X-Ray API の使用」を参照してください。