您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊
什麼是追蹤工具?
Trace 是一項疑難排解及監控在 Apigee Edge 中運作的 API Proxy 的工具。追蹤記錄可讓您透過 API Proxy 流程估算每個步驟的詳細資料。
請觀看這部影片,瞭解 Trace 工具。
如何使用 Trace
追蹤功能非常容易使用。您啟動了追蹤工作階段,然後對 Edge 平台發出 API 呼叫,並讀取結果。
- 按照下文說明存取 API Proxy 頁面。
Edge
如何使用 Edge UI 存取 API Proxy 頁面:
- 登入 apigee.com/edge。
- 在左側導覽列中,依序選取「Develop」(開發) >「API Proxy」。
傳統邊緣 (Private Cloud)
如何使用傳統版 Edge UI 存取 API Proxy 頁面:
- 登入
http://ms-ip:9000
,其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。 - 在頂端導覽列中,依序選取「API」>「API Proxy」。
- 在「API Proxy」頁面選取 API Proxy。
- 確認已部署您想追蹤的 API。
- 按一下「Trace」,前往追蹤記錄工具檢視畫面。
- 使用「Deployment to Trace」下拉式選單,選取要追蹤的部署環境和 Proxy 修訂版本。
- 按一下「開始追蹤工作階段」。Trace 工作階段處於啟用狀態時,API Proxy 會記錄處理管道中每個步驟的詳細資料。Trace 工作階段執行時,系統會從即時流量擷取訊息和比對內容資料。
- 如果沒有任何透過 Proxy 傳輸的即時流量,請直接傳送要求至 API。您可以使用任何想要傳送要求的工具,例如 curl、Postman 或任何您熟悉的工具。您也可以直接從 Trace 工具傳送要求。只要輸入網址並按一下「傳送」即可。注意:您只能透過 Trace 工具傳送 GET 要求,但無法傳送 POST 要求。
注意:一個追蹤工作階段可透過選定的 API Proxy,讓每個訊息處理器支援 10 項要求/回應交易。在 Edge 雲端中,2 個處理流量的訊息處理器支援 20 項要求/回應交易。如果您未手動停止追蹤工作階段,則追蹤記錄工作階段會在 10 分鐘後自動停止。
- 擷取足夠的要求後,請按一下「Stop Trace Session」。
- 已擷取的要求/回應交易清單會顯示在左選單中。點選任一交易即可查看詳細結果。
如何解讀追蹤記錄
追蹤工具包含交易對應和階段詳細資料兩個主要部分:
- 交易對應會使用「圖示」標示 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 結合。要求中必須包含所有指定的查詢和/或標頭名稱/值組合,才能成功比對。
- 篩選器工具不支援模式比對。
- 篩選器參數和值須區分大小寫。
如何建立追蹤記錄篩選器
- 如果追蹤工作階段正在執行,請按一下「Stop Trace Session」即可停止。
- 按一下 Trace 工具左上角的「篩選器」,展開「篩選器」欄位。
- 在「篩選器」欄位中,指定做為篩選依據的查詢參數和/或標頭值。本例中,我們指定兩個要篩選的查詢參數。要求中必須包含這兩個參數,系統才能成功比對。
- 啟動追蹤工作階段。
- 呼叫 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」按鈕。
Apigee 支援使用 Trace
根據預設,Apigee Edge 允許 Apigee 支援使用 API Proxy 的追蹤工具來提供支援。您可以隨時停用這個選項。不過,停用此選項可能會限制 Apigee 支援團隊的支援服務。
如要停用 Apigee 支援使用 Trace 工具:
- 登入 https://apigee.com/edge。
- 依序選取左側導覽列中的「管理」>「隱私權與安全性」。
- 按一下「Enable Apigee Support」(啟用 Apigee 支援) 切換鈕,停用 Apigee 支援團隊的 Trace 工具。