使用 Trace 工具

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件
資訊

什麼是追蹤工具?

Trace 是一項疑難排解及監控在 Apigee Edge 中運作的 API Proxy 的工具。追蹤記錄可讓您透過 API Proxy 流程估算每個步驟的詳細資料。

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

如何使用 Trace

追蹤功能非常容易使用。您啟動了追蹤工作階段,然後對 Edge 平台發出 API 呼叫,並讀取結果。

  1. 按照下文說明存取 API Proxy 頁面。

    Edge

    如何使用 Edge UI 存取 API Proxy 頁面:

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

    傳統邊緣 (Private Cloud)

    如何使用傳統版 Edge UI 存取 API Proxy 頁面:

    1. 登入 http://ms-ip:9000,其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。
    2. 在頂端導覽列中,依序選取「API」>「API Proxy」
  2. 在「API Proxy」頁面選取 API Proxy。
  3. 確認已部署您想追蹤的 API。
  4. 按一下「Trace」,前往追蹤記錄工具檢視畫面。
  5. 使用「Deployment to Trace」下拉式選單,選取要追蹤的部署環境和 Proxy 修訂版本。
  6. 按一下「開始追蹤工作階段」。Trace 工作階段處於啟用狀態時,API Proxy 會記錄處理管道中每個步驟的詳細資料。Trace 工作階段執行時,系統會從即時流量擷取訊息和比對內容資料。

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

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

如何解讀追蹤記錄

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

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

以下的追蹤記錄工具地圖範例標示了主要 Proxy 處理片段:

追蹤工具的交易對應關係

交易地圖圖例

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

交易地圖圖示

傳送要求至 API Proxy 的 ProxyEndpoint 的用戶端應用程式。
Proxy 流程中的圓圈標示轉換端點。每當要求從用戶端傳入、要求傳送至目標、回應從目標返回時,以及回應傳回用戶端時,系統就會發送這類通知。

長條表示 API Proxy 流程中資料流區隔的開頭。流程區隔為:ProxyEndpoint 要求、TargetEndpoint 要求、TargetEndpoint 回應和 ProxyEndpoint 回應,區隔包含 PreFlow、條件式流程和 PostFlow。

詳情請參閱設定流程一文。

表示 Analytics (分析) 動作曾發生在背景。

評估為 true 的條件式流程。如需條件式流程的簡介,請參閱設定流程

請注意,部分條件是由 Edge 產生。舉例來說,以下是 Edge 用來檢查 Proxy 端點中是否發生錯誤的運算式:

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

評估結果為 false 的條件式流程。如需條件式流程的簡介,請參閱設定流程

請注意,部分條件是由 Edge 產生。例如,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 Proxy 呼叫的後端目標。
時間線代表完成處理時間所需的時間 (以毫秒為單位)。比較經過時間區隔後,您就能找出執行時間最長的政策,以防導致 API 呼叫速度變慢。
Epsilon 表示時間範圍小於毫秒。

已停用。停用政策後,政策圖示會顯示出來。您可以透過公用 API 停用政策。請參閱 API Proxy 設定參考資料

發生錯誤,當政策步驟條件評估為 false (請參閱資料流變數和條件) 或執行 李 Fault 政策時,政策圖示就會顯示。
已略過。如果步驟條件經評估為 False,則未執行政策時,政策圖示會顯示出來。詳情請參閱流程變數和條件

瞭解階段詳細資料

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

階段詳細資料 說明
Proxy 端點 用於表示已選取執行的 ProxyEndpoint 流程。API Proxy 可以有多個已命名的 Proxy 端點。
變數

列出透過政策讀取及指派值的流程變數,另請參閱使用流程變數管理 Proxy 狀態

注意

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

使用篩選器調整訊息擷取

您可以指定標頭和/或查詢參數值,篩選要在 Trace 工具中顯示的要求。篩選器可讓您指定可能造成問題的呼叫。 舉例來說,如果要求包含特定內容或要求來自特定合作夥伴或應用程式,則您必須將其視為零。您可以篩選以下項目:

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

篩選器功能的注意事項

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

如何建立追蹤記錄篩選器

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

    Trace 工具中的「篩選器」側欄標籤會圈起來。
  3. 在「篩選器」欄位中,指定做為篩選依據的查詢參數和/或標頭值。本例中,我們指定兩個要篩選的查詢參數。要求中必須包含這兩個參數,系統才能成功比對。

    在追蹤工具中,「篩選器」下方的「查詢參數」下方設定了兩個範例名稱和值。
  4. 啟動追蹤工作階段。
  5. 呼叫 API。要求中必須包含所有指定標頭和/或查詢參數,才算是成功比對。

在「交易」下方,系統會顯示四個與兩個預設查詢參數相符的結果。

在上例中,這個 API 呼叫會顯示在 Trace 中:

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

但這不會:

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

使用 Trace 偵錯

追蹤記錄可讓您查看有關 API Proxy 的許多內部詳細資料。例如:

  • 方便您快速掌握哪些政策執行正確或失敗。
  • 假設您透過某個 Analytics (分析) 資訊主頁發現,其中一個 API 的效能異常降低。現在,您可以使用 Trace 找出瓶頸發生的位置。Trace 可以提供完成每個處理步驟所需的時間 (以毫秒為單位)。如果發現某個步驟花費的時間過長,可以採取修正措施。
  • 查看階段詳細資料,即可檢查傳送至後端的標頭、查看由政策設定的變數等。
  • 驗證基本路徑後,您就能確保政策會將郵件轉送至正確的伺服器。

選取檢視選項

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

選項 說明
顯示已停用的政策 顯示所有已停用的政策。您可以透過公用 API 停用政策。請參閱 API Proxy 設定參考資料
顯示略過的階段 顯示略過的階段。如果步驟條件經評估為 False,則未執行政策時,就會發生略過階段。詳情請參閱流程變數和條件
顯示所有 FlowInfo 代表流程片段內的轉場效果。
自動比較所選階段 比較所選階段與前一階段。如果關閉這項功能,系統就只會顯示所選階段。
顯示變數 顯示或隱藏已讀取和/或指派值的變數。
顯示屬性 屬性代表 API Proxy 的內部狀態。(預設為隱藏)。

正在下載追蹤記錄結果

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

如要下載,請點選「Download Trace Session」

以 curl 形式顯示要求

追蹤對目標伺服器發出的 API 呼叫後,您可以透過 curl 指令查看要求。這對偵錯來說特別實用,原因如下:

  • API Proxy 可能會修改要求,因此查看 Proxy 傳送至目標伺服器的要求與原始要求有何差異,會很有幫助。curl 指令代表修改過的要求。
  • 如果訊息酬載較大,curl 可讓您在單一位置查看 HTTP 標頭和訊息內容。(目前長度上限為 1,000 個字元。如要瞭解如何超過這個上限,請參閱這篇社群貼文)。

為了安全起見,curl 功能會遮蓋 HTTP Authorization 標頭。

如要在 Trace 收到 API 呼叫後將要求顯示為 curl,請在交易對應圖表中選取「要求已傳送至目標伺服器」階段,然後在「階段詳細資料」窗格的「傳送至目標伺服器的要求」欄中,按一下「顯示 curl」按鈕。

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

Apigee 支援使用 Trace

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

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

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