本文說明如何排解使用追蹤記錄探索工具頁面或舊版追蹤記錄探索工具頁面時的問題:
已知問題
本節列出已知問題:
使用 Telemetry API 寫入 Google Cloud 專案的時距,無法透過舊版 Trace Explorer 頁面存取。如要查看這些範圍,請使用預設的 Trace Explorer 頁面。
使用 Telemetry API 寫入 Google Cloud 專案的範圍無法透過 Cloud Trace API 存取。舉例來說,如果您嘗試列出這些追蹤記錄,指令就會失敗並顯示
404 Not Found
錯誤。
排解「Trace Explorer」頁面問題
本節說明如何排解使用「追蹤記錄探索器」頁面時的問題。
「Trace Explorer」頁面沒有資料
您正在使用「Trace 探索工具」頁面,但預期應有追蹤記錄資料時,卻無法在 Google Cloud 專案中查看任何追蹤記錄。
請嘗試以下步驟:
確認 Cloud Trace API 已啟用,且資料正在寫入專案:
在 Google Cloud 控制台中,前往「已啟用的 API 和服務」頁面:
如果列出 Cloud Trace API,請繼續下一個步驟。 如果沒有,請啟用 API。
如要啟用 API,請按一下「啟用 API 和服務」,搜尋「Cloud Trace API」,選取該選項,然後按一下「啟用」。
在「已啟用 API 和服務」頁面中,找出標示為「Cloud Trace API」的資料列。
如果標示為「錯誤」的資料欄列出非零值,表示透過 Cloud Trace API 讀取或寫入追蹤資料時發生錯誤。如要進一步瞭解錯誤來源,請選取「Cloud Trace API」,然後選取「指標」分頁標籤,並找出標示為「Errors by API method」(依 API 方法列出的錯誤) 的圖表:
如果寫入作業失敗,請授予提供驗證憑證的服務帳戶 Cloud Trace 代理者角色 (
roles/cloudtrace.agent
)。這個角色包含cloudtrace.traces.patch
權限,可讓應用程式將範圍資料寫入 Google Cloud 專案。詳情請參閱 Cloud Trace IAM 角色。
如果讀取作業失敗,請確認 Google Cloud 專案的 IAM 角色包含 Cloud Trace 使用者角色 (
roles/cloutrace.user
) 的權限。如需這個角色的權限清單,請參閱「Cloud Trace IAM 角色」。
「要求」欄會列出傳送至 Cloud Trace API 的要求數量。如果這個資料欄的值為零,表示沒有任何追蹤資料透過該 API 傳送。
App Engine、Cloud Run 和 Cloud Run 函式會傳送追蹤資料,而不使用 Cloud Trace API。如果您只使用這些服務,請前往下一個步驟。
如果應用程式透過 Cloud Trace API 傳送追蹤資料,但「要求」欄為零,請檢查應用程式和 Proxy,確認這些項目已設定為將追蹤記錄傳送至正確的專案。
在「Trace Explorer」頁面中,確認追蹤記錄儲存空間已初始化:
-
前往 Google Cloud 控制台的「Trace Explorer」頁面:
您也可以透過搜尋列找到這個頁面。
如果未初始化追蹤記錄儲存空間,「追蹤記錄探索工具」頁面會顯示含有下列文字的橫幅:
Trace storage is not initialized in this project. Enable trace storage to begin collecting trace data.
如要初始化追蹤記錄儲存空間,請按一下橫幅中的「啟用」。初始化作業通常會在幾分鐘內完成。
初始化成功後,系統會顯示通知橫幅。 追蹤會擷取過去一小時內傳送的追蹤資料,這些資料先前儲存在緩衝區中。過幾分鐘後,您就可以重新整理,因為資料會開始顯示在 Trace 探索工具中。
如果看到初始化失敗的錯誤訊息, Google Cloud 支援團隊成員必須手動解決問題。按一下「提出支援要求」即可開始這項程序。
-
確認「Trace 探索工具」頁面正在搜尋目前專案的追蹤記錄資料。在工具列中前往「範圍」元素,展開「縮小範圍」選單,選取「目前專案」,然後選取「套用」。
搜尋特定追蹤記錄失敗
在「Trace Explorer」頁面中輸入追蹤記錄 ID。找不到追蹤記錄,且畫面會顯示類似以下內容的訊息:
The select trace with ID abcde does not exist or is older than 30 days and has been deleted per our retention policy.
如要解決這項問題,請嘗試下列方法:
確認與追蹤記錄 ID 相關聯的時間戳記是否在保留期限內。
找出儲存追蹤記錄的 Google Cloud 專案,並確認 Google Cloud 控制台中的資源選擇工具已選取這個專案。根據預設,「Trace 探索工具」頁面只能存取所選專案中儲存的追蹤記錄資料。
「Trace Explorer」頁面缺少較舊的資料
您正在使用「Trace 探索工具」頁面,且可以查看近期資料,但將時間範圍選取器設為 30 天或更大的值時,系統不會顯示較舊的資料。
追蹤記錄探索器頁面不會顯示超過 Cloud Trace 資料保留期限 (30 天) 的時間範圍資料。
如果時間範圍選取器為 30 天或更短,則遺失的資料表示 Trace Explorer 頁面查詢的資料庫,是最近才建立,比您的時間範圍設定還新。舉例來說,如果您將這個值設為 20 天,但只能看到最近 10 天的資料,表示資料庫是在 10 天前建立。此外,這個資料庫只會包含在資料庫建立後傳送至 Google Cloud 專案的追蹤記錄。
如要查看及分析舊版追蹤記錄資料,請切換至舊版「Trace Explorer」頁面。這個頁面會從與 Trace Explorer 頁面不同的資料庫讀取追蹤記錄和範圍資料。
前往「Legacy Trace explorer」(舊版 Trace 探索工具)
追蹤記錄中缺少範圍
開啟「Trace Explorer」頁面,然後選取要查看的範圍。 「詳細資料」彈出式視窗會顯示追蹤記錄,但缺少部分範圍。
跨度可能遺失的原因如下:
「Trace 探索工具」頁面不會搜尋儲存追蹤記錄時距資料的所有 Google Cloud 專案。
您在儲存追蹤記錄範圍資料的 Google Cloud 專案中,身分與存取權管理角色不具備查看追蹤記錄資料的必要權限。
儀表化發生問題。舉例來說,只有部分追蹤記錄中的 span 會傳送至您的 Google Cloud 專案。
如要解決這些問題,請按照下列步驟操作:
在舊版「追蹤記錄探索工具」頁面中,判斷追蹤記錄是否完成:
在追蹤記錄的「詳細資料」彈出式視窗中,將追蹤記錄 ID 複製到剪貼簿。
前往舊版「Trace Explorer」頁面:
將追蹤記錄 ID 貼到「追蹤記錄 ID」欄位。
「追蹤記錄詳細資料」頁面會更新,並列出儲存追蹤記錄時距的專案。
如果追蹤記錄在舊版「Trace 探索工具」頁面中完整顯示,請返回「Trace 探索工具」頁面,然後將「範圍」元素設為追蹤記錄範圍,列出您在上一個步驟中識別的所有專案。這些專案會儲存所選追蹤記錄的時距。
如果沒有包含您在上一個步驟中識別專案的追蹤記錄範圍,請建立或修改現有的追蹤記錄範圍。詳情請參閱「建立及管理追蹤範圍」。
如果舊版 Trace 探索工具頁面未顯示完整追蹤記錄,表示系統未記錄範圍,或是您在儲存範圍資料的專案中,沒有 Cloud Trace 使用者角色 (
roles/cloudtrace.user
)。
您的權限不足,無法查看追蹤資料
您正在查看「Trace Explorer」頁面,並看到下列通知:
You don't have the required permissions to view trace data for one or more projects listed in the trace scope.
如要解決這個問題,請在工具列中執行下列操作:
- 展開「範圍」元素,找出所選的追蹤範圍。
- 在「縮小範圍」飛出式視窗中,選取「管理範圍」。
- 找出您在第一步中識別的追蹤範圍,然後展開詳細資料,查看 Google Cloud 專案清單。
- 針對追蹤範圍內的每個 Google Cloud 專案,確認您具備 Cloud Trace 使用者角色 (
roles/cloudtrace.user
)。如果您在專案中沒有該角色,請要求管理員或專案擁有者授予您該角色。
追蹤記錄儲存空間初始化失敗
您嘗試在「Trace 探索工具」顯示的橫幅上點選「啟用」,藉此初始化追蹤儲存空間,但看到下列錯誤訊息:
Initializing trace storage has failed for an unexpected reason. Please file a support ticket for assistance.
如果儲存空間初始化失敗,支援團隊成員必須手動解決問題。 Google Cloud 如要尋求支援,請按一下「提交支援單」。
排解舊版「Trace 探索工具」頁面的問題
本節說明如何排解使用舊版 Trace Explorer 頁面時的問題。
舊版介面中沒有資料
您使用的是舊版 Trace 探索工具頁面,但預期應有追蹤記錄資料時,卻無法在 Google Cloud 專案中查看任何追蹤記錄。
如要解決這項問題,請嘗試下列步驟:
-
Enable the Cloud Trace API.
在 Google Cloud 控制台中,前往「APIs & Services」(API 和服務) 頁面:
找到標示為「Cloud Trace API」的資料列後,請嘗試下列操作:
如果標示為「要求」的資料欄未列出任何數值資訊,表示沒有追蹤記錄資料傳送至 Google Cloud 專案。
如要解決這個問題,請檢查應用程式和 Proxy,確認這些項目已設定為將追蹤記錄傳送至正確的專案。
選取「Cloud Trace API」,然後選取「指標」分頁標籤,接著找出標示為「Errors by API method」(依 API 方法列出的錯誤) 的圖表:
如果寫入作業失敗,請授予提供驗證憑證的服務帳戶 Cloud Trace 代理者角色 (
roles/cloudtrace.agent
)。這個角色包含cloudtrace.traces.patch
權限,可讓應用程式將範圍資料寫入 Google Cloud 專案。詳情請參閱 Cloud Trace IAM 角色。
如果讀取作業失敗,請確認專案的 IAM 角色包含 Cloud Trace 使用者 (
roles/cloutrace.user
) 角色中的權限。如需這個角色的權限清單,請參閱「Cloud Trace IAM 角色」。 Google Cloud
舊版介面中沒有已部署應用程式的追蹤記錄資料
您已部署應用程式,並使用 Cloud Trace API 將資料傳送至 Google Cloud 專案,但系統未收集追蹤記錄資料。
建議您嘗試下列做法:
如果 Google Cloud 控制台的舊版 Trace 探索工具頁面未顯示任何資料,請按照「舊版 Trace 介面未顯示任何資料」一節中的步驟操作。
如果應用程式未部署在 Google Cloud 上,或使用服務帳戶提供驗證憑證,請確保服務帳戶已獲授 Cloud Trace 代理者角色 (
roles/cloudtrace.agent
)。這個角色包含
cloudtrace.traces.patch
權限,可讓應用程式將範圍資料寫入 Google Cloud 專案。如果應用程式使用 OpenTelemetry,請按照下列步驟操作:
如果是根服務,請嘗試更新環境變數,讓 OpenTelemetry 使用取樣率為
0.5
的traceidratio
取樣器:export OTEL_TRACES_SAMPLER="traceidratio" export OTEL_TRACES_SAMPLER_ARG="0.5"
如為其他服務,請保留
OTEL_TRACES_SAMPLER
環境變數未設定的狀態,以使用預設取樣器parentbased_always_on
。預設設定是指範圍的取樣決策會沿用自父項範圍 (如有)。如果沒有父項範圍,系統會對範圍進行取樣。
除非應用程式一律對每個範圍取樣,否則一般來說,無法強制追蹤端對端要求,因為端對端要求中的每個元件都會自行決定是否取樣。不過,您可以在追蹤記錄標頭中加入
sampled
旗標,並將這個旗標設為true
,藉此影響決策。這項設定會提示子項元件對要求進行取樣。如要進一步瞭解追蹤標頭,請參閱「用於脈絡傳播的通訊協定」。
追蹤記錄中缺少 span ID 訊息
追蹤記錄包含「Missing span ID」訊息。
在分散式追蹤系統中,不完整的追蹤記錄是預料中的情況。如果取樣的範圍包含對未接收到其他範圍的參照,追蹤記錄就會不完整。未解決的參照可能發生於下列情況:
- 參照的範圍未取樣。
- 參照的時距已取樣,但 Cloud Trace 尚未收到,或已收到但未儲存。
查看不完整的追蹤記錄時,Cloud Trace 會在追蹤記錄詳細資料窗格中顯示「Missing span ID」(缺少時距 ID) 訊息。
如果持續看到「缺少範圍 ID」訊息,請嘗試下列做法:
如果是您管理的元件,請確保這些元件會遵守並傳播標頭的
sampled
標記標記 (如果這個欄位存在)。這項設定會提示子元件對要求進行取樣。如要進一步瞭解追蹤標頭,請參閱「用於脈絡傳播的通訊協定」。Google Cloud 服務通常會遵守這項提示。不過,這些設定也會限制寫入追蹤資料的速率。
如果您使用 Cloud Service Mesh,請務必按照相關指南,傳播這些設定的追蹤內容。如需 Cloud Service Mesh 指引,請參閱「追蹤內容傳播」。
將 Go 應用程式更新為使用 OpenTelemetry 後,沒有任何追蹤資料
您的應用程式依賴用戶端程式庫擷取追蹤記錄,但更新應用程式以使用 OpenTelemetry 後,您就看不到 Cloud Trace 資料了。
由於部分 Go 適用的 Cloud 用戶端程式庫與 OpenCensus 整合,您必須使用 OpenCensus Bridge。如要進一步瞭解 Bridge 解決的問題,請參閱 OpenCensus Bridge。
如要瞭解 Go 適用的 Cloud 用戶端程式庫更新,請參閱問題 #4237。