疑難排解

本頁面提供 Trace 的疑難排解資訊。

已知問題

本節列出已知問題：

  • 使用 Telemetry API 寫入 Google Cloud 專案的範圍無法透過 Cloud Trace API 存取。舉例來說，如果您嘗試列出這些追蹤記錄，指令就會失敗並顯示 404 Not Found 錯誤。

排解記錄檔分析問題

本節說明如何解決使用 Log Analytics 查詢追蹤資料時可能發生的失敗情況。

顯示檢視畫面不存在的錯誤訊息

您在「記錄檔分析」頁面的查詢窗格中輸入 SQL 查詢，但 SQL 剖析器顯示下列錯誤：

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/views/OBS_VIEW_ID does not exist

如果系統找不到 FROM 陳述式中指定的檢視區塊，就會回報先前的錯誤。

如要解決這項錯誤，請確認檢視區塊的語法正確無誤：

  • 確認檢視區塊的完整名稱符合 Log Analytics 命名架構的必要語法。如要找出檢視區塊的必要語法，請顯示其預設查詢。

  • 如果 Google Cloud 專案 ID、位置、buckets ID、資料集 ID 或檢視表 ID 包含句號字元 (.)，請確認欄位是否以單一反引號 (`) 包裝。

    舉例來說，如果專案的 ID 為 example.com:bluebird，則 FROM 陳述式如下： Google Cloud 

    FROM `example.com:bluebird`.`us`.`_Trace`.`Spans`.`_AllSpans`

「Trace Explorer」頁面沒有資料

您有一個應用程式，會將追蹤記錄資料傳送至 Google Cloud 專案。 不過，當您開啟「追蹤記錄探索工具」頁面時，系統不會顯示任何資料。

無法查看追蹤資料的可能原因如下：

  • 您未取得查看資料所需的權限。
  • 追蹤範圍未傳送至專案。
  • 您的應用程式沒有寫入追蹤記錄資料所需的權限。
  • 系統不會儲存追蹤範圍。

以下小節提供資訊，說明如何排解所列失敗情境的問題。

確認您有權查看追蹤資料

如要查看追蹤記錄資料，請確認您已獲派 Cloud Trace 使用者角色 (roles/cloudtrace.user)。

確認追蹤範圍已傳送至專案

如要確認是否已將 span 傳送至專案，請按照下列步驟操作：

  1. Enable the Cloud Trace and Telemetry APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

    這兩個 API 都能擷取追蹤範圍。不過，建議使用 Telemetry API，因為它與 OpenTelemetry 生態系統相容，且限制比 Cloud Trace API 寬鬆。

  2. 前往「已啟用的 API 和服務」頁面，找出 Cloud Trace API 和 Telemetry API 的資料列。

    如果這兩個 API 的「要求」計數為零，表示沒有追蹤記錄資料傳送至專案。

確認應用程式具備寫入追蹤範圍的必要權限

如要判斷應用程式是否有權將追蹤資料寫入專案，請按照下列步驟操作：

  1. 前往「已啟用的 API 和服務」頁面，找出 Cloud Trace API 和 Telemetry API 的資料列，然後檢查「錯誤」欄。

  2. 如果任一 API 的「Errors」(錯誤) 欄顯示非零值，表示透過該 API 讀取或寫入追蹤資料時發生錯誤。如要找出錯誤類型，請選取 API，然後選取「指標」分頁，並查看「依 API 方法列出的錯誤」：

    如果寫入作業失敗，請將下列角色授予提供憑證的服務帳戶：

確認追蹤資料已儲存

追蹤範圍會儲存在名為 _Trace 的可觀測性值區中。當 Google Cloud 專案收到追蹤範圍時，系統會自動佈建該值區。不過，佈建作業可能會因多種情況而失敗。

如要判斷追蹤記錄資料是否有觀測功能 bucket，您可以 [列出觀測功能 bucket][trace-storage-list-buckets]，也可以開啟「Trace Explorer」頁面。舉例來說，您可以執行下列操作：

  1. 前往 Google Cloud 控制台的 「Trace Explorer」頁面：

    前往「Trace explorer」(Trace 探索工具)

    您也可以透過搜尋列找到這個頁面。

  2. 如果看到類似下方的橫幅，表示系統未佈建追蹤資料的儲存空間。

    Trace storage is not initialized for this project. Enable trace storage to begin collecting trace data.

    如要為追蹤記錄資料佈建可觀測性值區，請前往橫幅並點選「啟用」。

    點選「啟用」後，系統會將範圍傳送至專案。系統收到範圍後，會發出指令來建立名為 _Trace 的可觀測性值區。這項程序可能需要幾分鐘才能完成。

    初始化成功後，系統會顯示通知橫幅，且 Cloud Trace 會擷取過去一小時內傳送的所有追蹤資料。這項資料儲存在臨時緩衝區。資料可能需要幾分鐘才會顯示在 Trace 探索工具中。如果沒有看到任何資料，請重新整理視窗。

  3. 如果啟用指令失敗，系統會顯示下列訊息：

    Initializing trace storage has failed for an unexpected reason. Please file a support ticket for assistance.

    如要解決失敗問題，請按一下「File a ticket」(提交支援單) Google Cloud ，與支援團隊聯絡。

搜尋特定追蹤記錄失敗

在「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.

如要解決這項問題，請嘗試下列方法：

  1. 確認與追蹤記錄 ID 相關聯的時間戳記在保留期限內。

  2. 找出儲存追蹤記錄的 Google Cloud 專案，並確認 Google Cloud 控制台中的資源選擇工具已選取這個專案。根據預設，「Trace 探索工具」頁面只能存取所選專案中儲存的追蹤記錄資料。

「Trace Explorer」頁面缺少較舊的資料

您正在使用「Trace 探索工具」頁面，且可以查看近期資料，但將時間範圍選取器設為 30 天或更大的值時，系統不會顯示較舊的資料。

追蹤記錄探索頁面不會顯示超過 Cloud Trace 資料保留期限 (30 天) 的資料。

如果時間範圍選取器為 30 天或更短，則遺失的資料表示 Trace Explorer 頁面查詢的資料庫，是最近才建立，比您的時間範圍設定還新。舉例來說，如果將這個值設為 20 天，但只能看到最近 10 天的資料，表示資料庫是在 10 天前建立。此外，這個資料庫只會包含資料庫建立後傳送至 Google Cloud 專案的追蹤記錄。

顯示不完整的追蹤記錄

開啟「Trace Explorer」頁面，然後選取要查看的範圍。 「詳細資料」彈出式視窗會顯示追蹤記錄，但追蹤記錄不完整。系統不會顯示部分 span。

跨度可能遺失的原因如下：

  • 「Trace 探索工具」頁面不會搜尋所有 Google Cloud 專案，這些專案會儲存追蹤記錄的時距資料。

  • 您在儲存追蹤記錄跨度資料的 Google Cloud 專案中，身分與存取權管理角色不具備查看追蹤記錄資料的必要權限。

  • 儀表化問題。舉例來說，只有部分追蹤記錄中的 span 會傳送至您的 Google Cloud 專案。

如要解決這些問題，請按照下列步驟操作：

  1. 在「Trace 探索工具」頁面中，請務必將「範圍」元素設為追蹤記錄範圍，其中列出儲存所選追蹤記錄範圍的專案。

    如果沒有包含您在上一個步驟中識別專案的追蹤記錄範圍，請建立或修改現有的追蹤記錄範圍。詳情請參閱「建立及管理追蹤範圍」。

  2. 確認您在儲存時距資料的專案中，擁有 Cloud Trace User 角色 (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.

如要解決這個問題，請在工具列中執行下列操作：

  1. 展開「範圍」元素，找出所選的追蹤範圍。
  2. 在「縮小範圍」彈出式視窗中，選取「管理範圍」。
  3. 找出您在第一個步驟中識別的追蹤範圍，然後展開詳細資料，查看 Google Cloud 專案清單。
  4. 針對追蹤範圍內的每個 Google Cloud 專案，確認您具備 Cloud Trace 使用者角色 (roles/cloudtrace.user)。如果您在專案中沒有該角色，請要求管理員或專案擁有者授予您該角色。

追蹤記錄中缺少範圍 ID 訊息

追蹤記錄包含「Missing span ID」訊息。

在分散式追蹤系統中，不完整的追蹤記錄是預期會發生的情況。如果取樣的範圍包含對未接收範圍的參照，追蹤記錄就會不完整。未解決的參照可能發生於下列原因：

  • 參照的範圍未取樣。
  • 參照的時距已取樣，但 Cloud Trace 尚未收到，或已收到但未儲存。

查看不完整的追蹤記錄時，Cloud Trace 會在追蹤記錄詳細資料窗格中顯示「缺少時距 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。