分散トレースの有効化

このページの内容は Apigee と Apigee ハイブリッドに該当します。

Apigee Edge のドキュメントを表示する。

このページでは、Apigee ランタイムの分散トレースを構成するために必要な手順について説明します。分散トレースシステムを使うのが初めてで、詳細な情報が必要な場合は、分散トレースについてをご覧ください。

はじめに

分散トレースシステムを使うと、複数のアプリケーション、サービス、データベースに分散されたソフトウェアシステムとプロキシなどの中間要素でリクエストを追跡できます。このトレースシステムでは、リクエストの各ステップにかかった時間を示すレポートが生成されます。トレースレポートでは、リクエスト中に呼び出されたさまざまなサービスも詳細に示されるので、各ステップでソフトウェアシステムにおいて何が起こっているかをより深く理解できます。

API プロキシのトラブルシューティングとモニタリングでは、Apigee Edge のトレースツールと Apigee のデバッグツールを活用できます。ただし、これらのツールのデータは Cloud Trace や Jaeger などの分散トレースサーバーに送信されません。分散トレースレポートに Apigee ランタイムのデータを含めるには、Apigee ランタイムで分散トレースを明示的に有効化する必要があります。トレースが有効になると、ランタイムはトレースデータを分散トレースサーバーに送信して既存のトレースに参加できるようになります。その結果、Apigee エコシステム内外のデータを 1 か所で確認できます。

分散トレースレポートでは、次の情報を確認できます。

フロー全体の実行時間。
リクエストを受信した時刻。
リクエストをターゲットに送信した時刻。
ターゲットからレスポンスを受信した時刻。
フローの各ポリシーの実行時間。
サービスコールアウトとターゲットフローの実行時間。
レスポンスをクライアントに送信した時刻。

分散トレースレポートでは、フローの実行の詳細をスパンとして表示できます。スパンとは、トレース内のフローに要した時間を表します。フローの実行に要した時間は、フロー内の各ポリシーを実行するために必要な時間の合計として表示されます。次の各フローを個別のスパンとして表示できます。

リクエスト
- プロキシ
  - PreFlow
  - PostFlow
- ターゲット
  - PreFlow
  - PostFlow
レスポンス
- プロキシ
  - PreFlow
  - PostFlow
- ターゲット
  - PreFlow
  - PostFlow

Apigee ランタイムで分散トレースを有効にすると、デフォルトでは事前に定義された一連の変数がトレースされます。詳細については、トレースレポートのデフォルトのトレース変数をご覧ください。TraceCapture ポリシーを使用すると、ランタイムのデフォルトの動作を拡張して、追加のフロー、ポリシー、カスタム変数をトレースできます。詳細については、TraceCapture ポリシーをご覧ください。

Apigee への受信 API 呼び出しは既存のトレースの一部であるため、トレースヘッダーが含まれている場合があります。この場合、Apigee は既存のトレースに参加してヘッダーを送信 API 呼び出しに伝播します。Apigee ランタイムは Zipkin B3 ヘッダー形式を認識するため、既存のトレースに参加した場合は x-b3-traceid、x-b3-spanid、x-b3-sampled の各ヘッダーを認識します。ただし、受信 API 呼び出しにトレースヘッダーが存在しない場合、Apigee は独自のトレースヘッダーを追加して送信 API 呼び出しに伝播します。他のサービスは、必要に応じてヘッダーにアクセスし、トレースに参加できます。

トレースレポートのデフォルトのトレース変数

分散トレースを有効にすると、事前に定義された次の一連の変数をトレースレポートで確認できます。変数は次のスパンで表示されます。

POST_RESP_SENT: このスパンは、ターゲットサーバーからレスポンスを受信した後で追加されます。
POST_CLIENT_RESP_SENT: このスパンは、プロキシレスポンスをクライアントに送信した後で追加されます。

POST_RESP_SENT スパン内の変数

次の変数が POST_RESP_SENT スパンで表示されます。

REQUEST_URL (request.url)
REQUEST_VERB (request.verb)
RESPONSE_STATUS_CODE (response.status.code)
ROUTE_NAME (route.name)
ROUTE_TARGET (route.target)
TARGET_BASE_PATH (target.basepath)
TARGET_HOST (target.host)
TARGET_IP (target.ip)
TARGET_NAME (target.name)
TARGET_PORT (target.port)
TARGET_RECEIVED_END_TIMESTAMP (target.received.end.timestamp)
TARGET_RECEIVED_START_TIMESTAMP (target.received.start.timestamp)
TARGET_SENT_END_TIMESTAMP (target.sent.end.timestamp)
TARGET_SENT_START_TIMESTAMP (target.sent.start.timestamp)
TARGET_SSL_ENABLED (target.ssl.enabled)
TARGET_URL (target.url)

POST_CLIENT_RESP_SENT スパン内の変数

次の変数が POST_CLIENT_RESP_SENT スパンで表示されます。

API_PROXY_REVISION (apiproxy.revision)
APIPROXY_NAME (apiproxy.name)
CLIENT_RECEIVED_END_TIMESTAMP (client.received.end.timestamp)
CLIENT_RECEIVED_START_TIMESTAMP (client.received.start.timestamp)
CLIENT_SENT_END_TIMESTAMP (client.sent.end.timestamp)
CLIENT_SENT_START_TIMESTAMP (client.sent.start.timestamp)
ENVIRONMENT_NAME（environment.name）
FAULT_SOURCE (message.header + InternalHeaders.FAULT_SOURCE)
IS_ERROR (is.error)
MESSAGE_ID (message.id)
MESSAGE_STATUS_CODE (message.status.code)
PROXY_BASE_PATH (proxy.basepath)
PROXY_CLIENT_IP (proxy.client.ip)
PROXY_NAME (proxy.name)
PROXY_PATH_SUFFIX (proxy.pathsuffix)
PROXY_URL (proxy.url)

サポートされている分散トレースシステム

Apigee ランタイムは、次の分散トレースシステムをサポートしています。

Cloud Trace
Jaeger

トレースデータを Cloud Trace または Jaeger システムに送信するように Apigee ランタイムを構成できます。

Apigee ランタイム内のすべての API 呼び出しをトレースするとパフォーマンスに影響するため、Apigee では確率的サンプリングレートを構成できます。サンプリングレートを使用することによって、分散トレースのために送信される API 呼び出しの数を指定できます。たとえば、サンプリングレートを 0.4 として指定した場合、API 呼び出しの 40% がトレース用に送信されます。詳しくは、パフォーマンスに関する考慮事項をご覧ください。

構成可能な最大サンプリングレートは 0.5 です。

Cloud Trace 用に Apigee ランタイムを構成する

Apigee ランタイムと Apigee ハイブリッドランタイムのどちらも、Cloud Trace による分散トレースをサポートしています。Jaeger を使用している場合、このセクションをスキップして Jaeger 用の分散トレースの有効化に進んでください。

Cloud Trace 用に Apigee ランタイムを構成する

Apigee ランタイムで Cloud Trace を使用するには、Google Cloud プロジェクトで Cloud Trace API を有効にする必要があります。この設定により、Google Cloud プロジェクトは認証済みのソースからトレースデータを受信できます。

Cloud Trace API が有効になっていることを確認するには、次のようにします。

Google Cloud コンソールから [API とサービス] に移動します。
[API とサービス] に移動
[API とサービスの有効化] をクリックします。
検索バーで、「Trace API」と入力します。
[API が有効です] と表示されている場合、この API はすでに有効になっており、何もする必要はありません。それ以外の場合は、[有効にする] をクリックします。

Cloud Trace 用に Apigee ハイブリッドランタイムを構成する

Apigee ハイブリッドランタイムで Cloud Trace を使用するには、Cloud Trace API を有効にする必要があります。Cloud Trace API が有効になっていることを確認するには、Cloud Trace 用に Apigee ランタイムを構成するの手順に沿って操作します。

ハイブリッドランタイムで Cloud Trace を使用するには、Cloud Trace API を有効にしたうえで、サービスアカウント iam.gserviceaccount.com を追加する必要があります。このサービスアカウントとともに必要なロールと鍵を追加するには、次の手順を実行します。

新しいサービスアカウントを作成します。

gcloud iam service-accounts create \
    apigee-runtime --display-name "Service Account Apigee hybrid runtime" \
    --project PROJECT_ID

サービスアカウントに IAM ポリシーバインディングを追加します。

gcloud projects add-iam-policy-binding \
    PROJECT_ID --member "serviceAccount:apigee-runtime@PROJECT_ID.iam.gserviceaccount.com" \
    --role=roles/cloudtrace.agent --project PROJECT_ID

サービスアカウントキーを作成します。
```
gcloud iam service-accounts keys \
    create ~/apigee-runtime.json --iam-account apigee-runtime@PROJECT_ID.iam.gserviceaccount.com
```
サービスアカウントキーが正しく管理されていない場合は、セキュリティリスクが発生します。秘密鍵のセキュリティと、サービスアカウントキーを管理するためのベストプラクティスで説明されているその他の操作は、ユーザーの責任で実施してください。サービスアカウントキーを作成できない場合は、組織でサービスアカウントキーの作成が無効になっている可能性があります。詳細については、デフォルトで安全な組織リソースを管理するをご覧ください。
overrides.yaml ファイルにサービスアカウントを追加します。

envs:
 - name: ENV_NAME
   serviceAccountPaths:
   runtime: apigee-runtime.json
   synchronizer: apigee-sync.json
   udca: apigee-udca.json

ランタイムに変更を適用します。

apigeectl apply -f overrides.yaml --env=ENV_NAME

分散トレースを有効にする

Cloud Trace または Jaeger 用に分散トレースを有効にする前に、次の環境変数を作成します。

TOKEN="Authorization: Bearer $(gcloud auth print-access-token)"
ENV_NAME=YOUR_ENVIRONMENT_NAME
PROJECT_ID=YOUR_GOOGLE_CLOUD_PROJECT_ID

ここで

TOKEN は、署名なしトークンを含む認証ヘッダーを定義します。このヘッダーは、Apigee API を呼び出すときに使用します。詳細については、print-access-token コマンドのリファレンスページをご覧ください。
ENV_NAME は組織内の環境の名前です。
PROJECT_ID は、Google Cloud プロジェクトの ID です。

Cloud Trace 用に分散トレースを有効にする

次の例では、Cloud Trace 用に分散トレースを有効にする方法を示しています。

この Apigee API 呼び出しを実行します。
```
curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{"exporter":"CLOUD_TRACE","endpoint": "'"$PROJECT_ID"'",
    "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.1}}'
```
このサンプルリクエストの本文は、次の要素で構成されています。
- samplingRate は 0.1 に設定されています。これは、API 呼び出しの約 10% が分散トレースに送信されるということです。ランタイム環境での samplingRate の設定の詳細については、パフォーマンスに関する考慮事項をご覧ください。
- exporter パラメータは CLOUD_TRACE に設定されています。
- エンドポイントは、トレースの送信先の Google Cloud プロジェクトに設定されています。注: これは、構成手順で実行したサービスアカウントと一致する必要があります。
成功したときのレスポンスは次のようになります。
```
{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.1
  }
}
```

Jaeger 用に分散トレースを有効にする

次の例では、Jaeger 用に分散トレースを有効にする方法を示しています。

curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig' \
    -X PATCH \
    -H "content-type:application/json" -d '{
    "samplingConfig": {
    "samplingRate": 0.4,
    "sampler": "PROBABILITY"},
    "endpoint": "http://DOMAIN:9411/api/v2/spans",
    "exporter": "JAEGER"
    }'

この例で

samplingRate は 0.4 に設定されています。これは、API 呼び出しの約 40% が分散トレースに送信されるということです。
exporter パラメータは JAEGER に設定されています。
エンドポイントは、Jaeger がインストールされて構成された場所に設定されています。

コマンドを実行すると、次のようなレスポンスが表示されます。

{
  "exporter": "JAEGER",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.4
  }
}

分散トレースの構成を表示する

ランタイムの既存の分散トレース構成を表示するには、ランタイムにログインしてから、次のコマンドを実行します。

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig

コマンドを実行すると、次のようなレスポンスが表示されます。

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.1
  }
}

分散トレースの構成を更新する

次のコマンドは、Cloud Trace 用の既存の分散トレース構成を更新する方法を示しています。

curl -s \
    -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig?updateMask=endpoint,samplingConfig,exporter' \
    -X PATCH -H "content-type:application/json" \
    -d '{"samplingConfig": {"samplingRate": 0.05, "sampler":"PROBABILITY"},
    "endpoint":"staging", exporter:"CLOUD_TRACE"}'

コマンドを実行すると、次のようなレスポンスが表示されます。

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.05
  }
}

この例では、サンプリングレートが 0.05 に更新されています。

Jaeger 用の構成を更新する場合は、リクエストの exporter フィールドを JAEGER に設定します。

分散トレースの構成を無効にする

次の例は、Cloud Trace 用に構成された分散トレースを無効にする方法を示しています。

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH -d '{"exporter": "CLOUD_TRACE","endpoint": "'"$PROJECT_ID"'","samplingConfig":
    {"sampler": "OFF","samplingRate": 0.1}}'

コマンドを実行すると、次のようなレスポンスが表示されます。

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "OFF",
    "samplingRate": 0.1
  }
}

API プロキシ用のトレース設定をオーバーライドする

Apigee ランタイムで分散トレースを有効にすると、ランタイムのすべての API プロキシで同じトレース構成が使用されます。ただし、1 つ以上の API プロキシの分散トレース構成をオーバーライドすることも可能です。これにより、トレース構成をより詳細に制御できます。

次の例では、API プロキシ hello-world の分散トレース構成をオーバーライドしています。

curl -s -H "$TOKEN" \
     'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/ENV_NAME/traceConfig/overrides' \
     -X POST \
     -H "content-type:application/json" \
     -d '{"apiProxy": "hello-world","samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.1}}'

構成をオーバーライドすることで、すべての API プロキシの構成を変更せずに、特定の API プロキシの問題のトラブルシューティングを行うことができます。

トレース設定のオーバーライドを更新する

1 つ以上の API プロキシのトレース構成のオーバーライドを更新するには、次の手順を実施します。

次のコマンドを使用して、トレース構成の既存のオーバーライドを取得します。

curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides' \
    -X GET

このコマンドでは、次のようなレスポンスが返されます。このレスポンスには、オーバーライドの対象となる 1 つ以上のプロキシを識別する "name" フィールドが含まれています。

{
  "traceConfigOverrides": [
    {
      "name": "dc8437ea-4faa-4b57-a14f-4b8d3a15fec1",
      "apiProxy": "proxy1",
      "samplingConfig": {
        "sampler": "PROBABILITY",
        "samplingRate": 0.25
      }
    }
  ]
}

プロキシを更新するには、"name" フィールドの値を使用して、そのプロキシのオーバーライド構成に、更新されたフィールド値を含む POST リクエストを送信します。次に例を示します。

curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides/dc8437ea-4faa-4b57-a14f-4b8d3a15fec1' \
    -X POST \
    -H "content-type:application/json" \
    -d '{"apiProxy": "proxy1","samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.05}}'

トレース設定のオーバーライドを削除する

1 つ以上の API プロキシのトレース構成のオーバーライドを削除するには、次の手順を実施します。

次のコマンドを使用して、トレース構成の既存のオーバーライドを取得します。

curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides' \
    -X GET

{
  "traceConfigOverrides": [
    {
      "name": "dc8437ea-4faa-4b57-a14f-4b8d3a15fec1",
      "apiProxy": "proxy1",
      "samplingConfig": {
        "sampler": "PROBABILITY",
        "samplingRate": 0.25
      }
    }
  ]
}

プロキシを削除するには、"name" フィールドの値を使用して、そのプロキシのオーバーライド構成に、更新されたフィールド値を含む DELETE リクエストを送信します。次に例を示します。
```
curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides/dc8437ea-4faa-4b57-a14f-4b8d3a15fec1' \
    -X DELETE \
```

パフォーマンスに関する注意事項

Apigee ランタイム環境で分散トレースを有効にすると、パフォーマンスへの影響が予想され、メモリ使用量、CPU 要件、レイテンシが増加する可能性があります。影響の大きさは、API プロキシの複雑性（ポリシーの数など）と確率的サンプリングレート（samplingRate として設定）によって異なります。サンプリングレートが高いほど、パフォーマンスへの影響は大きくなります。パフォーマンスへの影響はいくつかの要因によって変化しますが、分散トレースの使用時にはパフォーマンスが 10～20% 低下することが見込まれます。

高トラフィックと低レイテンシの要件がある環境の場合、推奨される確率的サンプリングレートは 10% 以下です。トラブルシューティングに分散トレースを使用する場合は、特定の API プロキシに限定して確率的サンプリング（samplingRate）を増やすことを検討してください。

分散トレースの有効化

はじめに

トレース レポートのデフォルトのトレース変数

POST_RESP_SENT スパン内の変数

POST_CLIENT_RESP_SENT スパン内の変数

サポートされている分散トレース システム

Cloud Trace 用に Apigee ランタイムを構成する

Cloud Trace 用に Apigee ランタイムを構成する

Cloud Trace 用に Apigee ハイブリッド ランタイムを構成する

分散トレースを有効にする

Cloud Trace 用に分散トレースを有効にする

Jaeger 用に分散トレースを有効にする

分散トレースの構成を表示する

分散トレースの構成を更新する

分散トレースの構成を無効にする

API プロキシ用のトレース設定をオーバーライドする

トレース設定のオーバーライドを更新する

トレース設定のオーバーライドを削除する

パフォーマンスに関する注意事項

トレースレポートのデフォルトのトレース変数

サポートされている分散トレースシステム

Cloud Trace 用に Apigee ハイブリッドランタイムを構成する