Trace ツールの使用

Trace ツールとは

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

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

Trace の使用方法

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

下記の手順に沿って [API proxies] ページにアクセスします。
Edge

Edge UI を使用して [API proxies] ページにアクセスするには:
1. apigee.com/edge にログインします。
2. 左側のナビゲーションバーで [Develop] > [API Proxies] を選択します。
Classic Edge（Private Cloud）

注: Classic Edge UI は Edge for Private Cloud でのみ利用可能です。

Classic Edge UI を使用して [API proxies] ページにアクセスするには:
1. http://ms-ip:9000 にログインします。ここで、ms-ip は、Management Server ノードの IP アドレスまたは DNS 名です。
2. 上部のナビゲーションバーで [APIs] > [API Proxies] を選択します。
[API Proxies] ページの API プロキシを選択します。
トレースする API がデプロイされていることを確認します。
[Trace] をクリックして Trace ツールビューに移動します。
[Deployment to Trace] プルダウンメニューを使用して、トレースするデプロイ環境とプロキシリビジョンを選択します。
[Start Trace Session] をクリックします。Trace セッションがアクティブなときは、API プロキシにより処理パイプラインの各ステップの詳細が記録されます。Trace セッションの実行中は、ライブトラフィックからメッセージとコンテキストデータが取得されます。
プロキシを通過するライブトラフィックがない場合は、単に API にリクエストを送信します。リクエストの送信には、curl、Postman などの使い慣れた任意のツールを使用できます。また、Trace ツール自体からリクエストを直接送信することもできます。URL を入力して [Send] をクリックするだけです。

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

トレースの読み取り方法

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

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

次は、主なプロキシ処理セグメントにラベルを付けたサンプル 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 プロキシには、名前付きのプロキシエンドポイントが複数含まれていることがあります。
変数	ポリシーによって値の読み取りと値の割り当てが行われたフロー変数を一覧表示します。フロー変数でプロキシ状態を管理するもご覧ください。注: 等号（=）は、変数に割り当てられた値を示します。ノットイコール（≠）は、変数が読み取り専用であるか、またはポリシー実行中にエラーが発生したために、変数に値を割り当てられなかったことを示します。空のフィールドは、変数値が読み取られたことを示します。
リクエストヘッダー	HTTP リクエストヘッダーの一覧を表示します。
リクエストコンテンツ	HTTP リクエスト本文を表示します。
プロパティ（特性）	プロパティは、API プロキシの内部状態を表します。デフォルトでは表示されません。
ターゲットエンドポイント	実行対象として選択された TargetEndpoint を示します。
レスポンスヘッダー	HTTP レスポンスヘッダーの一覧を表示します。
レスポンスコンテンツ	HTTP レスポンスの本文を表示します。
PostClientFlow	リクエスト側のクライアントアプリにリクエストが返された後に実行される PostClientFlow の詳細を表示します。PostClientFlow に接続できるのは MessageLogging ポリシーのみです。現在、PostClientFlow は主に、レスポンスメッセージの開始と終了のタイムスタンプの間隔を測定するために使用されています。

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

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

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

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

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

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

トレースセッションが実行中の場合は、[Stop Trace Session] をクリックして停止します。
Trace ツールの左上にある [Filters] をクリックして、[Filters] フィールドを展開します。
[Filters] フィールドで、フィルタに使用するクエリパラメータまたはヘッダー値を指定します。この例では、フィルタに使用するクエリパラメータを 2 つ指定しています。正常に一致するには、どちらのパラメータもリクエストに含まれている必要があります。
トレースセッションを開始します。
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 では、デフォルトで API プロキシの Trace ツールを使用してサポートを提供できます。このオプションはいつでも無効にできます。ただし、このオプションを無効にすると、サポートを提供する Apigee サポートの機能が制限される場合があります。

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

https://apigee.com/edge にログインします。
左側のナビゲーションバーで [管理] > [プライバシーとセキュリティ] を選択します。
[Apigee サポートへのトレースを有効にする] トグルをクリックして、Apigee サポートによる Trace ツールの使用を無効にします。