このページは Cloud Translation API によって翻訳されました。

分散トレースの有効化

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

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

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

はじめに

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

Apigee Edge のトレースツールと Apigee のデバッグツールは、API プロキシのトラブルシューティングとモニタリングを実施する際に活用できます。ただし、これらのツールのデータは 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 Console から [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 プロキシの分散トレース構成をオーバーライドすることも可能です。これにより、トレース構成をより詳細に制御できます。

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

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 プロキシに特有の問題のトラブルシューティングを行うことができます。

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

API プロキシまたは 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}}'

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

API プロキシまたは 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 ハイブリッドランタイムを構成する