Trace ツールの使用

Trace ツールとは

Trace は、Apigee Edge で実行されている API プロキシのトラブルシューティングとモニタリングを目的としたツールです。Trace を使用すると、API プロキシのフローの各ステップの詳細を調べることができます。

Trace ツールの概要を説明する動画をご覧ください。

Trace の使用方法

Trace の使用方法は簡単です。トレース セッションを開始してから、Edge プラットフォームに対して API 呼び出しを行い、その結果を読み取ります。

  1. Trace ツールに移動します。
    • New Edge UI: 左側のナビゲーション バーで [Develop] > [API Proxies] を選択します。
    • Edge Classic UI: 上部のナビゲーション バーで [APIs] > [API Proxies] を選択します。
  2. [API Proxies] ページの API プロキシを選択します。
  3. トレースする API がデプロイされていることを確認します。
  4. [Trace] をクリックして Trace ツールビューに移動します。
  5. [Deployment to Trace] プルダウン メニューを使用して、トレースするデプロイメント環境とプロキシ リビジョンを選択します。
  6. [Start Trace Session] をクリックします。Trace セッションがアクティブなときは、API プロキシにより処理パイプラインの各ステップの詳細が記録されます。Trace セッションの実行中は、ライブ トラフィックからメッセージとコンテキスト データが取得されます。

  7. プロキシを通過するライブ トラフィックがない場合は、単に API にリクエストを送信します。リクエストの送信には、cURL、Postman などの使い慣れているツールを使用できます。また、Trace ツール自体からリクエストを直接送信することもできます。URL を入力して [Send] をクリックするだけです。

    注: 1 つの Trace セッションでは、選択されている API プロキシでメッセージ プロセッサあたり 10 件のリクエスト / レスポンス トランザクションをサポートできます。Edge クラウドでは、トラフィックを処理する 2 つのメッセージ プロセッサで、20 件のリクエスト / レスポンス トランザクションがサポートされています。トレース セッションは、手動で停止しなかった場合には 10 分後に自動的に停止します。
  8. 十分な数のリクエストを取得したら、[Stop Trace Session] をクリックします。
  9. 左側のメニューに取得したリクエスト / レスポンス トランザクションのリストが表示されます。いずれかのトランザクションをクリックすると、結果の詳細が表示されます。

トレースの読み取り方法

Trace ツールには、トランザクション マップとフェーズの詳細という主要な 2 つの部分があります。

  • トランザクション マップでは、アイコンを使用して、API プロキシ トランザクション中に発生した重要なステップ(ポリシー実行、条件ステップ、移行など)にそれぞれマークを付けます。アイコンにマウスカーソルを合わせると、概要情報が表示されます。リクエスト フローのステップはトランザクション マップの上部に横方向に表示され、レスポンス フローのステップはトランザクション マップの下部に横方向に表示されます。
  • ツールのフェーズの詳細セクションには、設定された変数または読み取られた変数、リクエストとレスポンスのヘッダーなど、プロキシの内部処理に関する情報が表示されます。アイコンをクリックすると、そのステップのフェーズの詳細が表示されます。

次は、主なプロキシ処理セグメントにラベルを付けたサンプル Trace ツールマップです。

Trace ツールのトランザクション マップ

トランザクション マップの凡例

次の表に、トランザクション マップに表示されるアイコンの目的を説明します。これらのアイコンは、プロキシフロー全体で重要な処理ステップにそれぞれマークを付けます。

トランザクション マップのアイコン

API プロキシの ProxyEndpoint にリクエストを送信するクライアント アプリ。
この丸では、プロキシフローの移行中のエンドポイントがマーキングされます。このアイコンが表示されるのは、リクエストがクライアントから到着するとき、リクエストがターゲットに送信されるとき、レスポンスがターゲットから戻ってくるとき、レスポンスがクライアントに戻されるときです。

この縦に長いバーでは、API プロキシのフロー内のフロー セグメントの開始が示されます。各フロー セグメントは、ProxyEndpoint リクエスト、TargetEndpoint リクエスト、TargetEndpoint レスポンス、ProxyEndpoint レスポンスです。セグメントには、PreFlow、条件フロー、および PostFlow が含まれています。

詳細については、フローの構成をご覧ください。

Analytics アクションがバックグラウンドで実行されていることを示します。

true と評価された条件フロー。条件フローの概要については、フローの構成をご覧ください。

一部の条件は Edge により生成されることに注意してください。たとえば、ProxyEndpoint でエラーが発生したかどうかを調べるために、次に示す式が Edge で使用されます。

((error.state equals PROXY_REQ_FLOW) or (error.state equals PROXY_RESP_FLOW))

false と評価された条件フロー。条件フローの概要については、フローの構成をご覧ください。

一部の条件は Edge により生成されることに注意してください。たとえば、TargetEndpoint でエラーが発生したかどうかを調べるために、次に示す式が Edge で使用されます。

(((error.state equals TARGET_REQ_FLOW) or (error.state equals TARGET_RESP_FLOW)) or ((error.state equals REQ_SENT) or (error.state equals RESP_START)))

ポリシー。ポリシーのタイプごとに、一意のアイコンがあります。これは、AssignMessage ポリシーのアイコンです。これらのアイコンにより、ポリシーが適切な順序で実行されているかどうかと、ポリシーの実行が成功したか失敗したかを確認できます。ポリシーのアイコンをクリックすると、ポリシーの実行結果と、その結果が予期されていた結果であるかどうかを確認できます。たとえば、メッセージが適切に変換されているかどうか、またはメッセージがキャッシュされているかどうかを確認できます。

適切に実行されているポリシーはチェックマークで明確に示されます。エラーの場合は、赤色の感嘆符がアイコンに表示されます。

ヒント: いずれかのポリシーが予想よりも長く時間がかかっているかどうかを確認するには、ツールチップまたはタイムラインに注目してください。

バックエンドのターゲットが Node.js アプリケーションの場合に表示されます。Apigee Edge における Node.js の概要をご覧ください。
API プロキシによって呼び出されるバックエンドのターゲット。
タイムラインには、処理の完了までにかかった時間(ミリ秒)が示されます。経過時間セグメントを比較すると、実行に最も時間がかかっている、API 呼び出しの速度を低下させているポリシーを特定できます。
Epsilon(イプシロン)では、ミリ秒より短いタイムスパンが示されます。

無効。ポリシーが無効になっているときに、ポリシーのアイコンに表示されます。ポリシーを公開 API で無効にすることができます。API プロキシ構成リファレンスをご覧ください。

エラー。ポリシー ステップ条件が false と評価されたときに、ポリシーのアイコンに表示されます(フローの変数と条件を参照)。また、RaiseFault ポリシーが実行されるたびに RaiseFault ポリシーのアイコンに表示されます。
スキップ。ステップ条件が false と評価されたために実行されなかったポリシーのアイコンにこれが表示されます。詳細については、フローの変数と条件をご覧ください。

フェーズの詳細について

このツールの [Phase Details] 部分から、各処理ステップでのプロキシの状態に関する情報を把握できます。以下は、[Phase Details] で表示される詳細の一部です。選択されているステップの詳細を確認するには、Trace ツールでアイコンをクリックし、ステップ間を移動するには [Next] / [Back] ボタンを使用します。

フェーズの詳細 説明
プロキシ エンドポイント 実行するために選択された ProxyEndpoint フローを示します。API プロキシには、名前付きのプロキシ エンドポイントが複数含まれていることがあります。
変数

ポリシーによって値が読み取られ、値が割り当てられたフロー変数をリストします。フロー変数でプロキシ状態を管理するをご覧ください。

:

  • 等号(=)は、変数に割り当てられた値を示します。
  • x が付いた等号(?)は、変数が読み取り専用であるか、またはポリシー実行中にエラーが発生したために、変数に値を割り当てられなかったことを示します。
  • 空のフィールドは、変数値が読み取られたことを示します。
リクエスト ヘッダー HTTP リクエスト ヘッダーの一覧を表示します。
リクエスト コンテンツ HTTP リクエスト本文を表示します。
プロパティ(特性) プロパティは、API プロキシの内部状態を表します。デフォルトでは表示されません。
ターゲット エンドポイント 実行対象として選択された TargetEndpoint を示します。
レスポンス ヘッダー HTTP レスポンス ヘッダーの一覧を表示します。
レスポンス コンテンツ HTTP レスポンスの本文を表示します。
PostClientFlow リクエスト側のクライアント アプリにリクエストが返された後に実行される PostClientFlow の詳細を表示します。PostClientFlow には MessageLogging ポリシーのみを接続できます。現在、PostClientFlow は主に、レスポンス メッセージの開始と終了のタイムスタンプの間隔を測定するために使用されています。

フィルタを使用したメッセージ キャプチャの調整

ヘッダーやクエリ パラメータ値を指定することで、Trace ツールに表示するリクエストをフィルタリングできます。フィルタにより、問題を引き起こしている可能性がある特定の呼び出しを絞り込むことができます。たとえば、特定の内容を含むリクエスト、または特定のパートナーまたはアプリから受信するリクエストに絞り込む必要が生じることがあります。次の項目でフィルタリングできます。

  • HTTP ヘッダー: 特定のヘッダーを含む呼び出しのみにトレースを限定します。これは問題のトラブルシューティングに役立つ優れた方法です。アプリのデベロッパーにヘッダーを送信して、問題を引き起こしている呼び出しにこのヘッダーを含めるように依頼できます。これ以降、Apigee Edge はその特定のヘッダーを含む呼び出しだけを記録するため、結果を調査できるようになります。
  • クエリ パラメータ: 特定のパラメータ値を含む呼び出しのみが記録されます。

フィルタ機能について知っておくべきこと:

  • フィルタのフィールドにフィルタ パラメータを指定した後、Trace セッションを開始し直す必要があります。
  • フィルタ パラメータは AND で結合されます。正常に一致するには、指定されたすべてのクエリとヘッダー名 / 値ペアのいずれかまたは両方が、リクエストに含まれている必要があります。
  • パターン照合は、フィルタツールではサポートされていません。
  • フィルタ パラメータと値では、大文字と小文字が区別されます。

トレース フィルタの作成方法

  1. トレース セッションが実行中の場合は、[Stop Trace Session] をクリックしてトレース セッションを停止します。
  2. Trace ツールの左上隅にある [Filters] をクリックして、[Filters] フィールドを展開します。


  3. [Filters] フィールドで、フィルタに使用するクエリ パラメータまたはヘッダー値を指定します。この例では、フィルタに使用するクエリ パラメータを 2 つ指定しています。正常に一致するには、どちらのパラメータもリクエストに含まれている必要があります。


  4. トレース セッションを開始します。
  5. API を呼び出します。指定されたすべてのヘッダーとクエリ パラメータを含むリクエストのみが一致します。

上記の例では、次の API 呼び出しが Trace に表示されます。

    http://docs-test.apigee.net/cats?name=Penny&breed=Calico
    

一方、次は表示されません。

    http://docs-test.apigee.net/cats?name=Penny
    

Trace によるデバッグ

Trace を使用すると、API プロキシ内部の詳細の多くを確認することができます。次に例を示します。

  • ポリシーが正しく実行されているか、失敗したかを一目で確認できます。
  • たとえば、Analytics のダッシュボードで、1 つの API で異常なパフォーマンス低下が発生していることに気づいたとします。この場合、Trace を使用するとボトルネックが発生している位置を特定できます。Trace では、各処理ステップの完了にかかった時間がミリ秒単位で示されます。1 つのステップに時間がかかりすぎていることが判明した場合は、是正処置を取ることができます。
  • [Phase Details] を確認すると、バックエンドに送信されているヘッダーや、ポリシーで設定された変数などを確認できます。
  • ベースパスを検証することで、ポリシーによってメッセージが正しいサーバーにルーティングされていることを確認できます。

View Options の選択

トレース セッションの「View Options」を選択します。

オプション 説明
Show Disabled Policies 無効化されたポリシーを表示します。公開 API でポリシーを無効にすることができます。API プロキシ構成リファレンスをご覧ください。
Show Skipped Phases スキップされたフェーズを表示します。ステップ条件が false に評価されたためにポリシーが実行されなかった場合に、フェーズがスキップされます。詳細については、フローの変数と条件をご覧ください。
Show all FlowInfos フロー セグメント内の遷移を表示します。
Automatically Compare Selected Phase 選択したフェーズを前のフェーズと比較します。選択したフェーズのみを表示するには、このオプションをオフにします。
Show Variables 値が読み取られて割り当てられた変数の表示 / 非表示を切り替えます。
Show Properties プロパティは、API プロキシの内部状態を表します。(デフォルトでは非表示)。

トレース結果のダウンロード

テキスト エディタを使ってオフラインで確認、検索するために、未加工のトレース結果の XML ファイルをダウンロードできます。このファイルには、すべてのヘッダー、変数、ポリシーの内容など、リスニング セッションの完全な詳細情報が含まれています。

ダウンロードするには、[Download Trace Session] をクリックします。

リクエストを cURL として表示する

ターゲット サーバーに対して行われた API 呼び出しをトレースした後は、cURL コマンドとしてリクエストを表示できます。これは、次のようないくつかの理由で、特にデバッグに役立ちます。

  • API プロキシがリクエストを変更する場合があります。したがって、プロキシからターゲット サーバーへのリクエストと元のリクエストとの相違点を確認するのに役立ちます。cURL コマンドは、変更されたリクエストを表示します。
  • 大きなメッセージ ペイロードの場合、cURL を使用すると、1 か所で HTTP ヘッダーとメッセージ コンテンツを確認できます。(現在、約 1,000 文字の制限があります。この制限の超過に関するヒントについては、コミュニティへのこの投稿をご覧ください。)

セキュリティ上の目的で、HTTP Authorization ヘッダーは cURL 機能によりマスキングされます。

Trace 経由で API 呼び出しが到着した後に cURL としてリクエストを表示するには、[Transaction Map] 図で [Request sent to target server] ステージを選択し、[Phase Details] ペインの [Request sent to target server] 列の [Show Curl] ボタンをクリックします。

Apigee での Trace の使用に関するサポート

Apigee Edge のデフォルトでは、Apigee のサポート担当者が API プロキシで Trace ツールを実行し、サポートを提供できる設定になっています。このオプションは、いつでも無効にできます。ただし、このオプションを無効にすると、Apigee が提供できるサポート内容が制限される場合があります。

Apigee サポートによる Trace ツールの使用を無効にするには:

  1. 新しい Edge UI(https://apigee.com/edge)にログインします。
  2. 左側のナビゲーション バーで [Admin] > [Privacy & Security] の順に選択します。
  3. [Enable Apigee Support to Trace] トグルをクリックして、Apigee サポートによる Trace ツールの使用を無効にします。