Send Docs Feedback

Note: Most user interface tasks can be performed in Edge Classic or the New Edge experience. For an overview, getting started topics, and release notes specific to the New Edge experience, see the docs.

Trace ツールの使用

Trace ツールとは?

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

Watch this video for an introduction to the Trace tool.

Trace の使用方法

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

  1. API メニューの「API Proxies」を選択します。 
  2. 「API Proxies」ページの API プロキシを選択します。
  3. トレースする API が展開されていることを確認します。
  4. Trace」をクリックして Trace ツールビューに移動します。 
  5. Deployment to Trace」ドロップダウンメニューを使用して、トレースする展開環境とプロキシの変更を選択します。 
  6. Start Trace Session」をクリックします。トレースセッションがアクティブなときは、API プロキシにより処理パイプラインの各ステップの詳細が記録されます。トレースセッションの実行中は、メッセージやコンテキストデータは、ライブトラフィックから取得されます。

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

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

トレースの読み取り方法

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

  • トランザクションマップではアイコンを使用して、ポリシー実行、条件ステップ、遷移などの API プロキシトランザクション中に発生した重要なステップをそれぞれマーキングします。サマリ情報を確認するには、アイコンにマウスポインタを重ねます。リクエストフローのステップはトランザクションマップの上側に横方向に表示され、レスポンスフローのステップはトランザクションマップの下側に横方向に表示されます。
  • ツールの「Phase Details」セクションでは、設定された変数または読み取られた変数、リクエストヘッダーとレスポンスヘッダー等を含む、プロキシの内部処理についての情報が一覧表示されます。そのステップの「Phase Details 」(フェーズの詳細) を参照するには、いずれかのアイコンをクリックします。

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

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

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

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

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

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

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

詳細については、「フローの構成」を参照してください。 

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

true と評価された条件フロー。条件フローの概要については、「フローの構成」を参照してください。

Note that some conditions are Edge-generated. For example, the following is an expression that Edge uses to check if an error occurred in the ProxyEndpoint:

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

false と評価された条件フロー。条件フローの概要については、「フローの構成」を参照してください。

Note that some conditions are Edge-generated. For example, the following is an expression that Edge uses to check if an error occurred in the TargetEndpoint:

(((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 proxy configuration reference」を参照してください。

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

フェーズの詳細について

このツールの「Phase Details」部分では、各処理ステップでのプロキシの状態の詳細を示します。以下は、「Phase Details」で表示される詳細の一部です。ステップの詳細を確認するには、Trace ツールでアイコンをクリックし、ステップ間を移動するには「Next」/「Back」ボタンを使用します。 

Trace captures message content. If your message payloads contain sensitive information, then you should enable data masking. For instructions, see Data masking and hiding.

Phase Detail 説明
プロキシエンドポイント 実行するために選択された ProxyEndpoint フローを示します。API プロキシには、名前付きのプロキシエンドポイントが複数ある場合があるためです。 
リクエストヘッダー HTTP リクエストヘッダーの一覧を表示します。
リクエストコンテンツ HTTP リクエスト本文を表示します。
プロパティ プロパティでは、API プロキシの内部状態を表します。デフォルトでは表示されません。
読み取られた変数 Lists the flow variables that were read by a policy. See also Managing proxy state with flow variables.
読み取り、割り当てられた変数 ポリシーによって値が読み取られ、割り当てられたフロー変数を一覧表示します。
ターゲットエンドポイント 実行のために選択された TargetEndpoint を示します。 
レスポンスヘッダー HTTP レスポンスヘッダーの一覧を表示します。
レスポンスコンテンツ HTTP レスポンス本文を表示します。 
PostClientFlow リクエスト側のクライアントアプリにリクエストが返された後に実行される PostClientFlow に関する詳細を表示します。PostClientFlow に添付できるのは、MessageLogging ポリシーのみです。PostClientFlow フローは、現在、レスポンスメッセージの開始と終了のタイムスタンプの間隔を測定するために主に使用されています。

トランザクションのフィルタリング

ヘッダーやクエリーパラメータ値を指定することで、Trace ツールにどのリクエストを表示するかをフィルタリングできます。 

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

  • フィルタフィールドでフィルタパラメータを指定したら、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 プロキシ内部の詳細の多くを確認することができます。次に例を示します。

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

「View Options」の選択

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


 

オプション 説明
Show Disabled Policies 無効化されたポリシーを表示します。ポリシーはパブリック API で無効にすることができます。「API proxy configuration reference」を参照してください。
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 コマンドでは変更されたリクエストが表示されます。
  • For larger message payloads, the cURL allows you to see the HTTP headers and message content in a single place. (There's currently a limit of about 1,000 characters. For a tip on getting past this limit, see this community post.)

セキュリティを確保するため、HTTP 承認ヘッダーは cURL 機能によりマスキングされます。

API プロキシでリクエストストリームが有効になっている (リクエストとレスポンスのストリーム配信を参照) ​​場合は、リクエスト本文は使用できません。

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

 

 

Help or comments?