Trace UI を使用する

このセクションでは、新しいデバッグ セッションを作成し、リクエスト / レスポンス データを表示する方法について説明します。また、以前のデバッグ セッションを表示し、ハイブリッド UI でデバッグ セッションにフィルタを適用する方法についても説明します。

ハイブリッド UI で新しいデバッグ セッションを作成する

新しいデバッグ セッションを作成すると、UI または API などの外部ソースで作成されたリクエストのリクエスト データとレスポンス データを UI で確認できます。バックグラウンドで、トレースは UI で開始されなかったリクエストのデータも記録しています。

ハイブリッド UI で新しいデバッグ セッションを作成するには:

  1. ブラウザで Apigee ハイブリッド UI を開きます。
  2. メインビューから [API Proxies] を選択します。
  3. デバッグするプロキシを選択します。

    デプロイビューが表示されます。

  4. デプロイビューの右上にある [Trace] タブをクリックします。

    タブ

    トレースビューには次の情報が表示されます。

    トレースビュー

  5. [Start a trace session] パネルで次の操作を行います。
    1. [Env] プルダウン リストから、デバッグする API プロキシの環境とリビジョン番号を選択します。
    2. 次に [Start a trace session] パネルの例を示します。

      トレースビューを開始する

    3. (省略可)[Filter] プルダウン リストから、作成するデバッグ セッションのすべてのトランザクションに適用するフィルタを選択します。デフォルトは「None」です。この場合、トレースデータのすべてのトランザクションが含まれます。

      フィルタの使用方法については、フィルタをご覧ください。組み込みフィルタの詳細については、定義済みフィルタの使用をご覧ください。

    4. [Start Trace Session] をクリックします。

      ハイブリッド UI の [Trace details] パネルに、ID を含む現在のトレース セッションの詳細が表示されます。

      UI で新しいデバッグ セッションを作成しましたが、収集するデータが生成される前にリクエストを送信する必要があります。

      [Trace details] パネルでは、次の操作を行うことができます。

      アイコン 関数 説明
      ダウンロード アイコン ダウンロード アクティブ セッションのトレースデータをダウンロードします。このデータはオフラインで表示できます。
      戻るアイコン 戻す 前のパネルに戻ります。ここで別のデバッグ セッションを開始できます。現在のデバッグ セッションは、タイムアウトになるか、トランザクション数に達するまで継続します。
      削除アイコン 削除 現在選択されているデバッグ セッションのデータを削除します。セッションのデータは削除されますが、セッションは停止しません。

      UI で開始したトレース セッションのデフォルトのタイムアウトは 10 分です。これは API で開始したセッションと異なります。

      [Start Trace Session] をクリックするとすぐに時間の計測が始まります。できるだけ多くのデータを収集する場合は、次のステップが終わってから [Start Trace Session] をクリックします。

  6. [Request / Response] パネルで次の操作を行います。
    1. [URL] フィールドに、リクエストの送信先となるエンドポイントを入力します。必要に応じて、クエリ文字列パラメータを URL に追加します。GET 以外のリクエストは送信できません。
    2. [Request / Response] パネルには、UI で行ったリクエストのデータのみが表示されます。ただし、UI で開始していないリクエストのデータも記録されています。

    3. [Send] をクリックします。

      Apigee は指定された URL にリクエストを送信します。[Send] をクリックするたびに、ハイブリッド UI により [Trace details] パネルにリクエストが記録されます。

      次の例は、成功した複数のリクエストを示しています(HTTP ステータス コード 200 が返されています)。

      キャプチャされたトレース リクエスト

      UI では、[Request / Response] パネルの [Transaction Map] セクションと [Phase Details] セクションにトレースデータが表示されます。また、次の例のように [Proxy Endpoint]、[Request Headers]、[Request Content]、[Properties] セクションの値が自動的に更新されます。

      キャプチャされたトレース リクエスト

      フェーズ、トランザクション マップ、[Request / Response] ビューの他のセクションの詳細については、トレースツールを使用するをご覧ください。

    デバッグ セッションがアクティブになり、すべてのリクエストのデータが記録されます(除外されている場合を除く)。タイムアウトに達するか、セッションで記録されたリクエスト数が上限を超えるまで、セッションはアクティブな状態を持続します。

  7. UI では、任意の数のデバッグ セッションを新規に作成できます。詳しくは、別のデバッグ セッションを開始するをご覧ください。

アクティブ セッションの停止とセッション データの削除

アクティブなデバッグ セッションを途中で停止することはできません。ただし、アクティブ セッションのデータは削除可能です。この操作を行うには、そのセッションの [Trace details] パネルにある削除アイコン(削除アイコン)をクリックします。

あるいは、アクティブ セッションが終了するまで待ちます。

別のデバッグ セッションを開始する

デバッグ セッションの実行中に、ハイブリッド UI で別のセッションを開始することもできます。この操作を行うには、[Trace details] パネルで戻るアイコン()をクリックします。

戻るアイコンをクリックすると、トレース セッションの開始パネルに戻ります。

UI に [Start a trace session] パネルが表示され、新しいデバッグ セッションを開始できます。

最近のデバッグ セッションを表示する

Apigee ハイブリッドでは、デバッグ セッションのデータが 24 時間保存されます。この構成はできません。データは 24 時間後に使用できなくなります。その前であれば、ハイブリッド UI にデバッグ セッションを表示できます。

後で参照できるように、デバッグ セッション データをダウンロードしておくことをおすすめします。

最近のデバッグ セッションを表示するには:

  1. ブラウザで Apigee ハイブリッド UI を開きます。
  2. メインビューから [API Proxies] を選択します。
  3. デバッグするプロキシを選択します。
  4. [Deployments] ビューの右上にある [Trace] タブをクリックします。
  5. [Recent trace sessions] パネルで次の操作を行います。
    1. [Env] プルダウン リストから、デバッグ セッションを表示する API プロキシの環境を選択します。
    2. [Rev] プルダウン リストから、デバッグ セッションを表示する API プロキシのリビジョン番号を選択します。

    次の例のように、使用可能なデバッグ セッションのリストがハイブリッド UI に表示されます。

    最近のトレース セッション

  6. 表示するセッションのリンクをクリックします。

    ハイブリッド UI にデバッグ セッションが読み込まれ、[Request / Response] パネルにトレースデータが自動的に入力されます。

デバッグ セッション データ

未加工のトレース結果が保存されているファイルをダウンロードして、オフラインで表示できます。ダウンロードされたファイルには、すべてのヘッダー、変数、ポリシーの内容を含むデバッグ セッションの詳細が含まれています。

UI でデバッグ セッション データのダウンロードまたは表示ができる期間は 24 時間です。この時間が経過すると、ハイブリッドはセッション データを削除します。

デバッグ セッション データをダウンロードする

現在のデバッグ セッションのトレースデータをダウンロードするには:

  • アクティブ セッション: [Trace details] パネルのダウンロード アイコン(ダウンロード アイコン)をクリックします。
  • 前のセッション: [Recent trace sessions] パネルでセッションの名前をクリックします(最近のデバッグ セッションを表示するを参照)。その後、[Trace details] パネルにある ダウンロード アイコン をクリックします。

データ構造をダウンロードする

ハイブリッドの Trace UI でダウンロードされるセッション データは、ハイブリッドのトレース API を使用するでダウンロードされるデータと異なります。

UI のダウンロード:

  • セッション全体のすべてのトランザクションが含まれます。
  • トランザクションを Messages 配列に格納します。
  • セッションに関するメタデータが DebugSession オブジェクトとして格納されます。

反対に、API を使用してデータをダウンロードする場合、取得できるトランザクションは 1 回に 1 つだけです。詳しくは、トランザクションをダウンロードするをご覧ください。

ダウンロード データの例

次の例では、ダウンロードされたデータの DebugSession メタデータ オブジェクトがハイライト表示されています。このオブジェクトの後に、セッション内のトランザクションを含む Messages 配列が続きます。

{
  "DebugSession": {
    "Retrieved": "2019-06-08T13:08:13.395Z",
    "Organization": "myorg",
    "Environment": "prod",
    "API": "myproxy",
    "Revision": "1",
    "SessionId": "a2a271aa-4242-4ac6-97cb-aec8dcb115a9"
  },
  "Messages": [
    {
      "completed": true,
      "point": [
        {
          "id": "Paused"
        },
        {
          "id": "Resumed"
        },
        {
          "id": "StateChange",
          "results": [
            {
              "ActionResult": "DebugInfo",
              "properties": {
                "property": [
                  {
                    "name": "To",
                    "value": "REQ_HEADERS_PARSED"
                  },
                  {
                    "name": "From",
                    "value": "REQ_START"
                  }
                ]
              },
              "timestamp": "8-6-19 13:08:37:718"
            },
            {
              "ActionResult": "RequestMessage",
              "headers": [
                {
                  "name": "accept",
                  "value": "*/*"
                },
                {
                  "name": "accept-encoding",
                  "value": "gzip,gzip,deflate,br"
                },
                {
                  "name": "content-length",
                  "value": "0"
                },
                {
                  "name": "host",
                  "value": "myorg.example.domain.net"
                },
                {
                  "name": "user-agent",
                  "value": "Google-Apigee"
                },
                {
                  "name": "x-b3-sampled",
                  "value": "0"
                },
                {
                  "name": "x-b3-spanid",
                  "value": "d4ee579206759662"
                },
                {
                  "name": "x-b3-traceid",
                  "value": "adc1e171777c237dd4ee579206759662"
                },
                {
                  "name": "x-forwarded-for",
                  "value": "66.102.8.98"
                },
                {
                  "name": "x-forwarded-proto",
                  "value": "https"
                },
                {
                  "name": "x-request-id",
                  "value": "54e05cba-4242-4490-4242-60c45c156f90"
                }
              ],
              "uRI": "/myproxy",
              "verb": "GET"
            }
          ]
        },
        {
          "id": "FlowInfo",
          "results": [
            {
              "ActionResult": "DebugInfo",
              "properties": {
                "property": [
                  {
                    "name": "environment.name",
                    "value": "prod"
                  },
                  {
                    "name": "environment.qualifiedname",
                    "value": "myorg__prod"
                  },
                  {
                    "name": "environment.orgname",
                    "value": "myorg"
                  }
                ]
              },
              "timestamp": "8-6-19 13:08:37:718"
            }
          ]
        },
        {
          "id": "FlowInfo",
          "results": [
            {
              "ActionResult": "DebugInfo",
              "properties": {
                "property": [
                  {
                    "name": "organization.name",
                    "value": "myorg"
                  }
                ]
              },
              "timestamp": "8-6-19 13:08:37:718"
            }
          ]
        },
        {
          "id": "FlowInfo",
          "results": [
            {
              "ActionResult": "DebugInfo",
              "properties": {
                "property": [
                  {
                    "name": "apiproxy.qualifiedname",
                    "value": "myproxy__1"
                  },
                  {
                    "name": "apiproxy.basepath",
                    "value": "/"
                  },
                  {
                    "name": "apiproxy.revision",
                    "value": "1"
                  },
                  {
                    "name": "apiproxy.name",
                    "value": "myproxy"
                  }
                ]
              },
              "timestamp": "8-6-19 13:08:37:718"
            }
          ]
        },
        ...
      ...
    }
  ]
}

デバッグ セッションにリクエストが含まれていなかった場合、次の例のように Message 配列が空になっています。

{
  "DebugSession": {
    "Retrieved": "2019-06-08T13:08:13.395Z",
    "Organization": "myorg",
    "Environment": "prod",
    "API": "myproxy",
    "Revision": "1",
    "SessionId": "a2a271aa-4242-4ac6-97cb-aec8dcb115a9"
  },
  "Messages": []
}

API ダウンロード データの構造

Trace API でダウンロードしたデバッグ セッション データには、次のように、単一のトランザクション オブジェクトが含まれます。

{
  "completed": true,
  "point": [
    ...
  ...
}

Trace API では、同時に 1 つのトランザクションをダウンロードできます。1 回の API 呼び出しでセッション全体をダウンロードすることはできません。詳しくは、トランザクションをダウンロードするをご覧ください。

ダウンロードしたトレースデータを表示する

ハイブリッド UI では、ダウンロードしたトレースデータをオフラインで表示できます。

ダウンロードしたトレースデータを表示するには:

  1. ブラウザで Apigee ハイブリッド UI を開きます。
  2. メインビューから [API Proxies] を選択します。
  3. [Develop] > [Offline Trace] の順に選択します。

    [Offline Trace] ビューが表示されます。

    オフライン トレースのビュー

  4. [Offline Trace] ビューにデータを読み込むには、[Choose File] ボタンをクリックします。

    トレース ファイルのデータが読み込まれ、ハイブリッド UI に表示されます。

    ハイブリッド UI の実際のオフライン トレースデータのビューです。

    [Offline Trace] ビューの次のリージョンをメモします。

    • 左上: リクエスト タイプが表示されます。リクエスト内を移動するには、この領域を使用します。
    • 左下: 構成オプションが表示されます。詳しくは、トレースツールを使用するを参照してください。
    • 右上: トレース セッションの詳細が表示されます。
    • 中央右: API プロキシからのリクエストのパスが表示されます。このパスはトランザクション マップともいいます。ここには、検出されたポリシーと、ポリシーの実行時にエラーが発生したかどうかが示されます。
    • 右下: 現在選択しているリクエストのヘッダーが表示されます。

    ハイブリッド UI でトレースデータを表示する場合、さまざまなオプションを切り替えることができます。たとえば、無効なポリシーを表示するかどうかや、変数とプロパティを表示するかどうかを設定できます。詳しくは、Edge ドキュメントのトレースを使用したデバッグをご覧ください。

事前定義のフィルタを使用する

ハイブリッド UI では、事前に定義されたフィルタを使用できます。独自のフィルタを作成しなくても、一般的なフィルタを使用できます。

UI で新しいデバッグ セッションを作成する場合、[Start a trace session] パネルで事前定義のフィルタを選択できます。

次の表に、事前定義のフィルタを示します。

フィルタ名 説明
Response Time Greater Than

レイテンシの問題を確認します。

  • target.duration はターゲットのレイテンシです。または、リクエストが送信され、ターゲットからレスポンスを受信するまでの時間(ミリ秒)です(target.received.end.timestamptarget.sent.start.timestamp の差で計算します)。
  • client.duration はクライアントのレイテンシです。または、リクエストが送信され、クライアントからレスポンスを受信するまでの時間(ミリ秒)です(client.received.end.timestampclient.sent.start.timestamp の差で計算します)。

例:


target.duration > 420 && client.duration > 1000

詳細については、フロー変数リファレンスclienttarget をご覧ください。

Response Code

HTTP レスポンス コードが指定された値と一致するかどうかを確認します。例:


response.status.code <= 599
Header

指定されたリクエスト ヘッダーが指定された値と等しいかどうかを確認します。例:


request.header.cache-control.1 == "16544"
Path

リクエストが指定されたパスと一致するかどうかを確認します。値にワイルドカード マッチングを使用できます。例:


request.path == /myproxy/customer/4*
Query Param

指定されたリクエスト クエリ パラメータが指定された値と等しいかどうかを確認します。例:


request.queryparam.lang == "language:en-us"
Custom

独自の式を挿入できます。フロー変数リファレンスにある任意のオブジェクトと条件リファレンスの構文を使用できます。また、カスタム変数を使用することもできます。

カスタム フィルタの作成方法については、フィルタをご覧ください。