使用 Trace 工具

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

什麼是 Trace 工具?

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

觀看這部影片,瞭解 Trace 工具。

如何使用 Trace

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

  1. 按照下方說明,前往「API Proxy」頁面。

    邊緣

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

    1. 登入 apigee.com/edge。
    2. 在左側導覽列中,依序選取「Develop」>「API Proxies」。

    新版 Edge UI (私有雲)

    如要使用新版 Edge UI 存取 API Proxy 頁面,請按照下列步驟操作:

    1. 登入新版 Edge UI,網址為 http://host:3001/edge,其中 host 是執行新版 Edge UI 的主機 IP 位址或 DNS 名稱。
    2. 在左側導覽列中,依序選取「Develop」>「API Proxies」。
  2. 在「API Proxy」頁面選取 API Proxy。
  3. 請確認您要追蹤的 API 已部署。
  4. 按一下「Trace」,前往 Trace 工具檢視畫面。
  5. 使用「Deployment to Trace」(要追蹤的部署作業) 下拉式選單,選取要追蹤的部署環境和 Proxy 修訂版本。
  6. 按一下「Start Trace Session」。追蹤工作階段啟用時,API Proxy 會記錄處理管道中每個步驟的詳細資料。追蹤工作階段執行期間,系統會從即時流量擷取訊息和比對內容資料。

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

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

如何解讀追蹤記錄

追蹤工具主要分為兩個部分:交易對應和階段詳細資料:

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

以下是追蹤工具地圖範例,其中標示了主要 Proxy 處理區隔:

追蹤工具的交易對應

交易對應圖例

下表說明交易對應中圖示的意義。這些圖示會標示 Proxy 流程中每個重要的處理步驟。

交易地圖圖示

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

高長條表示 API Proxy 流程中流程區隔的開頭。流程區隔包括: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 政策執行時,顯示在 RaiseFault 政策圖示上。
已略過。如果政策因步驟條件評估為 false 而未執行,政策圖示上會顯示這個圖示。 詳情請參閱「流程變數和條件」。

瞭解階段詳細資料

工具的「Phase Details」(階段詳細資料) 部分會提供許多有關 Proxy 在每個處理步驟中的狀態資訊。以下是「階段詳細資料」中提供的部分詳細資料。按一下追蹤工具中的任何圖示,即可查看所選步驟的詳細資料,或使用「Next」(下一步)/「Back」(返回) 按鈕,在步驟之間移動。

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

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

注意:

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

使用篩選器精細調整訊息擷取

您可以指定標頭和/或查詢參數值,篩選追蹤工具中顯示的要求。篩選器可讓您指定可能造成問題的特定呼叫。舉例來說,您可能需要鎖定含有特定內容的請求,或來自特定合作夥伴或應用程式的請求。可篩選的項目包括:

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

篩選器功能須知

  • 在篩選器欄位中指定篩選器參數後,必須重新啟動 Trace 工作階段。
  • 篩選器參數會以 AND 運算子連結。要求中必須包含所有指定的查詢和/或標頭名稱/值組合,才能成功比對。
  • 篩選器工具不支援模式比對。
  • 篩選器參數和值會區分大小寫。

如何建立追蹤記錄篩選器

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

    在 Trace 工具中,「篩選器」側欄標籤會以圓圈標示。
  3. 在「篩選器」欄位中,指定要篩選的查詢參數和/或標頭值。在這個範例中,我們指定了兩個查詢參數做為篩選條件。要求中必須同時提供這兩個參數,才能成功比對。

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

「Transactions」下方會顯示四個符合兩項預設查詢參數的結果。

在上述範例中,這項 API 呼叫會顯示在 Trace 中:

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

但不會:

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

使用 Trace 偵錯

Trace 可讓您查看 API Proxy 的許多內部詳細資料。例如:

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

選取檢視畫面選項

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

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

下載追蹤記錄結果

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

如要下載,請按一下「Download Trace Session」。

以 curl 顯示要求

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

  • API Proxy 可能會修改要求,因此建議您查看 Proxy 傳送至目標伺服器的要求與原始要求有何不同。curl 指令代表修改後的要求。
  • 如果是較大的訊息酬載,curl 可讓您在單一位置查看 HTTP 標頭和訊息內容。(目前上限約為 1,000 個字元。如需突破這項限制的訣竅,請參閱這篇社群貼文。

基於安全考量,curl 功能會遮蓋 HTTP 授權標頭。

如要在 API 呼叫通過 Trace 後,以 curl 形式查看要求,請在「Transaction Map」圖表中選取「Request sent to target server」階段,然後在「詳細資料窗格」的「Request sent to target server」欄中,按一下「Show curl」按鈕。

圖片註解指出「Show Curl」按鈕,以及「Transaction Map」圖表中的其中一個圓圈。

Apigee 支援團隊使用 Trace

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

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

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