使用 Trace 工具

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

什麼是「追蹤」工具？

「追蹤」工具可監控在 Apigee Edge 上執行的 API Proxy，並排解相關問題，追蹤功能可讓您透過 API Proxy 流程，探測每個步驟的詳細資料。

如需追蹤工具簡介，請觀看這部影片。

如何使用「追蹤」

Trace 簡單易用。您會啟動追蹤工作階段，然後對 Edge 平台發出 API 呼叫，並讀取結果。

  1. 存取 API Proxy 頁面，詳情請參閱下文。

    邊緣

    如要使用 Edge 使用者介面存取 API Proxy 頁面，請按照下列步驟操作：

    1. 登入 apigee.com/edge。
    2. 在左側導覽列中，依序選取「開發」>「API Proxy」。

    新版 Edge 使用者介面 (私有雲)

    如要使用 New Edge UI 存取 API Proxy 頁面，請按照下列步驟操作：

    1. 在 http://host:3001/edge 登入 New Edge UI，其中 host 是執行 New Edge UI 的主機 IP 位址或 DNS 名稱。
    2. 在左側導覽列中，依序選取「開發」>「API Proxy」。
  2. 從「API Proxy」頁面選取 API Proxy。
  3. 請務必部署要追蹤的 API。
  4. 按一下「追蹤」，前往「追蹤工具」檢視畫面。
  5. 使用「部署作業至追蹤」下拉式選單，選取要追蹤的部署環境和 Proxy 修訂版本。
  6. 按一下「Start Trace Session」。追蹤工作階段啟動後，API Proxy 會記錄處理管道中每個步驟的詳細資料。追蹤工作階段執行期間，系統會從即時路況擷取訊息和情境資料。

  7. 如果沒有任何即時流量流經 Proxy，只要向 API 傳送要求即可。您可以使用任何工具傳送要求，例如 curl、Postman 或任何您熟悉的工具。或者，您也可以直接透過「追蹤」工具傳送要求。只要輸入網址，然後按一下「傳送」即可。注意：您只能從「追蹤」工具傳送 GET 要求，但無法傳送 POST 要求。

    注意：透過所選 API Proxy，每個訊息處理器的一個追蹤記錄工作階段最多可支援 10 項要求/回應交易。在 Edge Cloud 中，如果使用 2 個訊息處理器處理流量，則支援 20 個要求/回應交易。如果沒有手動停止追蹤工作階段，系統會在 10 分鐘後自動停止。
  8. 擷取足夠數量的要求後，請按一下「Stop Trace Session」(停止追蹤工作階段)。
  9. 左選單會顯示擷取的請求/回應交易清單。點選任一筆交易即可查看詳細結果。

如何解讀追蹤記錄

追蹤工具主要分為兩部分：交易地圖和階段詳細資料：

  • 交易地圖會使用圖示標示 API Proxy 交易期間發生的每個重要步驟，包括政策執行、條件步驟和轉換。將滑鼠游標懸停在任一圖示上，即可查看摘要資訊。交易地圖頂端會顯示要求流程步驟，底部則會顯示回應流程步驟。
  • 工具的「階段詳細資料」部分會列出 Proxy 內部處理作業的相關資訊，包括已設定或讀取的變數、要求和回應標頭等。按一下任一圖示，即可查看該步驟的階段詳細資料。

以下是追蹤工具地圖範例，並標示了主要的 Proxy 處理區段：

追蹤工具的交易地圖

交易地圖圖例

下表說明交易地圖中顯示的圖示用途。這些圖示會標示整個 Proxy 流程中每個重要的處理步驟。

交易地圖圖示

用戶端應用程式會將要求傳送至 API Proxy 的 ProxyEndpoint。
圓圈標示 Proxy 流程中的轉換端點。當用戶端傳送要求、要求傳送至目標、目標傳回回應，以及回應傳回用戶端時，這些函式都會存在。

高條形表示 API 代理流程中流程區隔的開頭。流程 區段包括：ProxyEndpoint 要求、TargetEndpoint 要求、TargetEndpoint 回應和 ProxyEndpoint 回應。區隔包含 PreFlow、條件式流程和 PostFlow。

詳情請參閱「設定流程」。

表示 Analytics 動作已在背景執行。

評估結果為 true 的條件式流程。如需條件式流程的簡介，請參閱「設定流程」。

請注意，部分條件是由 Edge 產生。舉例來說，以下是 Edge 用來檢查 ProxyEndpoint 是否發生錯誤的運算式：

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

評估結果為 false 的條件式流程。如要瞭解條件式流程簡介，請參閱「設定流程」。

請注意，部分條件是由 Edge 產生。舉例來說，以下是 Edge 用來檢查 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 Proxy 呼叫的後端目標。
時間軸會指出處理時間長度 (以毫秒為單位)。比較經過的時間區隔，有助於找出執行時間最長，導致 API 呼叫速度變慢的政策。
Epsilon 表示小於一毫秒的時間間隔。

已停用。政策停用時，政策圖示上會顯示這個圖示。您可以使用公用 API 停用政策。請參閱 API Proxy 設定參考資料。
發生錯誤，當政策步驟條件評估結果為 false 時 (請參閱「流程變數和條件」)，或每當執行 RaiseFault 政策時，政策圖示上就會顯示此圖示。
已略過。如果步驟條件評估結果為 false，導致政策未執行，政策圖示上就會顯示這個圖示。詳情請參閱「流程變數和條件」。

瞭解階段詳細資料

工具的「階段詳細資料」部分會顯示每個處理步驟的 Proxy 狀態。以下是「階段詳細資料」提供的部分詳細資料。按一下追蹤工具中的任何圖示，即可查看所選步驟的詳細資料，或使用「下一步」/「上一步」按鈕在各步驟之間移動。

階段詳細資料 說明
Proxy 端點 指出選取要執行的 ProxyEndpoint 流程。API Proxy 可以有多個具名 Proxy 端點。
變數

列出政策讀取並指派值的流程變數。另請參閱「使用流程變數管理 Proxy 狀態」。

注意：

  • 等號 (=) 表示指派給變數的值。
  • 等號加上刪除線 (≠) 表示變數無法指派值，因為變數為唯讀，或政策執行時發生錯誤。
  • 如果欄位空白，表示系統已讀取變數值。
要求標頭 列出 HTTP 要求標頭。
要求內容 顯示 HTTP 要求主體。
屬性 屬性代表 API Proxy 的內部狀態。這些項目預設不會顯示。
目標端點 指出選取要執行的 TargetEndpoint。
回應標頭 列出 HTTP 回應標頭。
回覆內容 顯示 HTTP 回應主體。
PostClientFlow 顯示 PostClientFlow 的相關資訊，要求傳回給要求用戶端應用程式後，系統就會執行 PostClientFlow。只有 MessageLogging 政策可以附加至 PostClientFlow。PostClientFlow 目前主要用於測量回應訊息的開始和結束時間戳記之間的時間間隔。

使用篩選器調整訊息擷取作業

您可以指定標頭和/或查詢參數值，篩選要在「追蹤」工具中顯示的要求。篩選器可讓您找出可能導致問題的特定呼叫。 舉例來說，您可能需要專注於含有特定內容的要求，或是來自特定合作夥伴或應用程式的要求。你可以依下列條件篩選：

  • HTTP 標頭 - 將追蹤記錄限制為僅包含特定標頭的呼叫。這有助於排解問題。您可以將標頭傳送給應用程式開發人員，請對方在造成問題的呼叫中加入標頭。接著，Apigee Edge 只會記錄含有該特定標頭的呼叫，方便您檢查結果。
  • 查詢參數：系統只會記錄參數值符合特定條件的通話。

篩選功能須知

  • 在篩選器欄位中指定篩選器參數後，您必須重新啟動追蹤工作階段。
  • 篩選參數會以 AND 運算子合併。所有指定的查詢和/或標頭名稱/值配對都必須出現在要求中，才能成功比對。
  • 篩選器工具不支援模式比對。
  • 篩選器參數和值會區分大小寫。

如何建立追蹤記錄篩選器

  1. 如果追蹤工作階段正在執行，請按一下「停止追蹤工作階段」停止。
  2. 按一下「追蹤」工具左上角的「篩選器」，展開「篩選器」欄位。

    在「追蹤」工具中，系統會圈選「篩選器」側邊列標籤。
  3. 在「篩選條件」欄位中，指定要篩選的查詢參數和/或標頭值。在本例中，我們指定了兩個查詢參數來進行篩選。要求中必須同時提供這兩項參數，才能成功比對。

    在「追蹤」工具的「篩選器」下方，以及「查詢參數」下方，系統會設定兩個範例名稱和值。
  4. 啟動追蹤工作階段。
  5. 呼叫 API。只有包含所有指定標頭和/或查詢參數的要求，才會成功比對。

在「交易」下方，會顯示四個符合兩個預設查詢參數的結果。

在上述範例中，這個 API 呼叫會顯示在追蹤記錄中：

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

但不會：

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

使用 Trace 偵錯

追蹤功能可讓您查看 API Proxy 的許多內部詳細資料。例如：

  • 您可以一目瞭然哪些政策執行正確，哪些政策執行失敗。
  • 假設您透過其中一個 Analytics 資訊主頁發現，某個 API 的效能異常下滑，現在，您可以使用「追蹤」功能，找出發生瓶頸的位置。追蹤記錄會提供每個處理步驟完成所需的時間 (以毫秒為單位)。如果發現某個步驟耗時過長，可以採取修正措施。
  • 查看階段詳細資料，即可檢查傳送至後端的標頭、查看政策設定的變數等。
  • 驗證基本路徑後，即可確保政策將訊息轉送至正確的伺服器。

選取檢視選項

選擇追蹤工作階段的檢視選項。

選項 說明
顯示已停用的政策 顯示任何已停用的政策。您可以使用公用 API 停用政策。請參閱 API Proxy 設定參考資料。
顯示已略過的階段 顯示所有略過的階段。如果步驟條件評估結果為 false，系統就不會執行政策，並略過該階段。詳情請參閱「流程變數和條件」。
顯示所有流程資訊 代表流程區隔內的轉場效果。
自動比較所選階段 比較所選階段與前一階段的資料。關閉這項設定，即可只查看所選階段。
顯示變數 顯示或隱藏已讀取和/或指派值的變數。
顯示屬性 屬性代表 API Proxy 的內部狀態。(預設為隱藏)。

下載追蹤結果

您可以下載原始追蹤結果的 XML 檔案，在文字編輯器中離線查看及搜尋。檔案會顯示監聽工作階段的完整詳細資料，包括所有標頭、變數和政策的內容。

如要下載，請按一下「下載追蹤工作階段」。

以 curl 顯示要求

追蹤對目標伺服器發出的 API 呼叫後，您可以將要求視為 curl 指令。這項功能特別適合用於偵錯，原因如下：

  • API Proxy 可能會修改要求，因此查看 Proxy 對目標伺服器的要求與原始要求有何不同，會很有幫助。curl 指令代表修改後的要求。
  • 如果訊息酬載較大，您可以使用 curl 在單一位置查看 HTTP 標頭和訊息內容。(目前長度上限約為 1,000 個半形字元。如需如何突破這項限制的提示，請參閱這篇社群貼文。

為確保安全，curl 功能會遮蓋 HTTP 授權標頭。

如要在「追蹤」中查看以 curl 形式顯示的要求 (API 呼叫傳送後)，請在「交易地圖」圖表中選取「傳送至目標伺服器的要求」階段，然後按一下「階段詳細資料」窗格中「傳送至目標伺服器的要求」欄的「顯示 curl」按鈕。

圖片註解指出「顯示 Curl」按鈕，以及「交易地圖」圖表中的其中一個圓圈。

Apigee 支援使用追蹤記錄

根據預設，Apigee Edge 允許 Apigee 支援使用 API Proxy 的追蹤工具來提供支援。您可以隨時停用這個選項。不過，停用此選項可能會限制 Apigee 支援團隊的支援服務。

如要停用 Apigee 支援使用 Trace 工具：

  1. 登入 https://apigee.com/edge。
  2. 依序選取左側導覽列中的「管理」>「隱私權與安全性」。
  3. 按一下「Enable Apigee Support」(啟用 Apigee 支援) 切換鈕，停用 Apigee 支援團隊的 Trace 工具。