トレースの概要

Apigee ハイブリッドでは、API プロキシのリクエストとレスポンスのフロー全体を示すトレースデータを収集できます。これには、ポリシー実行時に適用されるすべてのリクエストとレスポンスのパラメータが含まれます。プロキシの開発とデプロイで、デバッグやトラブルシューティングを行う場合に重要な情報となります。

トレースアーキテクチャ

次の図は、新しいデバッグセッションを作成するプロセスを示しています。

デバッグセッションの開始リクエストの概要

ポーリングは非同期で行われるため、ハイブリッドトレースデータはリアルタイムで利用できません。Cloud の Apigee Edge でトレースを使用する場合と比べると、トレースデータが使用可能になるまで少し時間がかかります。

トレースデータは管理プレーンに 24 時間保存されます。

トレースを使用する

このセクションでは、ハイブリッドでトレースを使用する方法の概要を説明します。詳細は、以降のセクションで説明します。

要件

トレースを使用するには、次の構成が必要です。

サービスアカウント:

apigee-synchronizer（ロール: Apigee Synchronizer 管理者）
apigee-udca（ロール: Apigee Analytics エージェント）

詳細については、サービスアカウントの作成をご覧ください。

Synchronizer:

Synchronizer アクセス
すべての Synchronizer ノードのクロックが UTC で同期している必要があります。

デバッグセッションの終了

デバッグセッションを作成すると、次の 2 つのプロパティによってセッションが終了するタイミングが決まります。

タイムアウト: セッション中にデータを収集する期間。デフォルトの長さは、セッションの開始方法（API または UI）によって異なります。最大値は 600 秒（10 分）です。
ヒント: ハイブリッド UI で新しいデバッグセッションを作成するときは、タイムアウトを構成できません。ただし、トレース API を使用して新しいセッションを作成するときは、タイムアウトを構成できます。
カウント: Message Processor ごとに 1 つのセッションで記録される最大リクエスト数。ほとんどのクラスタで Message Processor の数は可変であるため、カウントの影響は予測できません。この設定のカスタマイズは、おすすめしません。

タイムアウトかこのカウントに到達すると、その Message Processor のデバッグセッションが終了します。

このセクションでは、デバッグセッションの説明で次の用語を使用します。

アクティブセッション。タイムアウトに到達していないか、そのカウントを超過していないデバッグセッションです。アクティブセッションでは、フィルタで除外されていないリクエストのデータが記録されます。
完了セッション。タイムアウトに到達したか、そのカウントを超過したデバッグセッションです。完了セッションでは新しいリクエストのデータは記録されません。セッションが終了してから 24 時間以内にデータが削除されます。

ハイブリッド UI でトレースを使用する

次のセクションでは、ハイブリッド UI でトレースを使用する方法について説明します。

Trace API を使用する

Trace API セクションでは、次の API の使用方法について説明します。

Debug Sessions API（Create Debug Sessions API、Delete Data Debug Sessions API、List Debug Sessions API を含む）
Debug Session Data API（Get Debug Session Data API、List Debug Session Data API を含む）

Edge とハイブリッドでのトレースの違い

次の表に、Apigee ハイブリッドと Apigee Edge のトレースの違いを示します。

機能	Apigee Edge Cloud	Apigee ハイブリッド
適時性	リアルタイム、同期	わずかな遅延、非同期
セッション名 / ID	ユーザーからセッション名を取得	ユーザーからのセッション名を取得しない
フィルタ	基本的なフィルタのサポート（ヘッダーパラメータ、クエリパラメータフィルタなど）	複雑なフィルタリング論理のサポート（AND 論理演算、OR 論理演算など）。任意のフロー変数（フロー変数のリファレンスを参照）へのアクセス。構文は、条件リファレンスにある条件と同じです。
セッションタイムアウト	デバッグセッションの長さとデータの保持期間を定義します。 API 呼び出しで開始した場合のデフォルト値は 20 分、UI で開始した場合は 10 分です。	デバッグセッションの長さのみを定義します。Message Processor がデバッグモードで実行するリクエストを受信したときが開始ポイントになります。セッションが API で開始した場合のデフォルト値は 5 分、UI で開始した場合は 10 分です。 24 時間が経過するとデータが自動的に削除されます。
データマスキング		^{ハイブリッドのデータマスキングは、不具合により意図したとおりに機能しません。回避策として、トレースデータが Trace API やハイブリッド UI で使用可能になったらデータを削除できます。}
セッションの有効期限		セッション作成リクエストの有効期間。この時間内にデバッグセッションが開始しない場合、Synchronizers はセッション作成リクエストを無視します。前提条件に記載されているように、Synchronizers のクロックを同期させてください。
トレースのリクエスト数	Message Processor あたり 20 まで	Message Processor あたりのデフォルトは 10、最大値は 15 です。
API	Apigee Edge Cloud	Apigee ハイブリッド
Apigee ハイブリッドは Debug Sessions API と Debug Session Data API を公開していますが、Apigee API 経由で次を行うことはできません。
デバッグセッションの停止
特定のトランザクションの削除

フィルタ

新しいデバッグセッションを作成するときに、セッションにフィルタを追加すると、ハイブリッドが必要なデータのみを返すように設定できます。フィルタは、ハイブリッドがリクエストメッセージとレスポンスメッセージの評価で使用する条件文であり、これによってトレースデータをデバッグセッションに含めるかどうかが決定されます。

フィルタの構文

フィルタは、条件リファレンスで説明した Edge 条件と同じ構文をサポートしています。次の操作が含まれます。

フィルタは、フロー変数リファレンスと記述されているフロー変数とカスタム変数にアクセスできます。次の例に、フィルタで使用できるフロー変数の一部を示します。

# Response codes:
  response.status.code <= 599
  response.status.code >=301 &amp;&amp; response.status.code <=420

# Requests/responses:
  request.verb == "GET"
  request.header.A == 'B' || request.queryparam.X == 'Y'

# Query parameters:
  request.queryparam.myparam == 'fish'
  (request.queryparam.param1 == 'X' || request.queryparam.param2 == 'Y') &amp;&amp; request.queryparam.param3 == 'Z'

# Faults:
  fault.code != 'messaging.runtime.RouteFailed'
  fault.name == 'IPDeniedAccess'

カスタム変数の使用方法については、Apigee コミュニティで Apigee Edge でカスタム属性を使用する方法をご覧ください。

デバッグセッションでフィルタを使用する

新しいデバッグセッションでフィルタを使用するには:

ハイブリッド UI: [Filters] プルダウンリストから使用可能なオプションの 1 つを選択します（Trace UI を使用するを参照）。あるいは、[Custom Filter] を選択し、上記の構文で独自のフィルタを作成します。
Apigee API: デバッグセッション作成リクエストに filter オブジェクトを追加します（Hybrid Trace API を使用するを参照）。

Apigee ハイブリッドでは、クエリ文字列にフィルタを追加できません。

セッション後の開始後にデバッグセッションにフィルタを追加することはできません。フィルタを追加するには、新しいデバッグセッションを作成する必要があります。