トレースの概要

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

トレース アーキテクチャ

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

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

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

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

トレースを使用する

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

前提条件

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

サービス アカウント:

  • apigee-synchronizer(役割: Apigee Synchronizer 管理者)
  • apigee-udca(役割: Apigee Analytics エージェント)

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

Synchronizer:

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

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

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

  • タイムアウト: セッションがデータを収集する期間。デフォルトは 300 秒(または 5 分)です。最大値は 600 秒(または 10 分)です。
  • カウント: Message Processor ごとに 1 つのセッションで記録される最大リクエスト数。ほとんどのクラスタで Message Processor の数は可変であるため、カウントの影響は予測できません。この設定のカスタマイズはおすすめしません。

このいずれかに達すると、その Message Processor のデバッグ セッションが終了します。

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

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

デバッグ セッションのタイムアウトは Hybrid UI で構成できません。タイムアウトは、新しいデバッグ セッションの作成時に Trace API で構成できます。

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

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

Trace API を使用する

Trace API セクションでは、次の 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 APIDebug 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 ハイブリッドでは、クエリ文字列にフィルタを追加できません。

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