疑難排解

本文說明如何使用 Trace Explorer 頁面或舊版 Trace Explorer 頁面時排解問題：

• 排解「Trace Explorer」頁面的問題
• 排解舊版 Trace Explorer 頁面的問題

已知問題

本節列出已知問題：

• 使用 Telemetry API 寫入 Google Cloud 專案的時距，無法透過舊版 Trace Explorer 頁面存取。如要查看這些跨度，請使用預設的 Trace Explorer 頁面。

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

排解「Trace Explorer」頁面問題

本節說明如何使用 Trace Explorer 頁面排解問題。

「Trace Explorer」頁面中沒有資料

您使用「Trace 探索工具」頁面，但在 Google Cloud 專案中無法查看任何追蹤記錄，即使您預期會顯示追蹤記錄資料。

請嘗試以下步驟：

1. 確認已啟用 Cloud Trace API，且資料正在寫入專案：

   1. 在 Google Cloud 控制台中，前往「已啟用的 API 和服務」頁面：

      前往「已啟用的 API 和服務」

   2. 如果列表中顯示 Cloud Trace API，請繼續進行下一個步驟。否則請啟用 API。

      如要啟用 API，請按一下「啟用 API 和服務」，搜尋「Cloud Trace API」，選取該選項，然後按一下「啟用」。

2. 在「Enable APIs and Services」頁面中，找出標示為「Cloud Trace API」的資料列。

3. 「Requests」欄會列出傳送至 Cloud Trace API 的要求數量。如果這個欄為零，表示沒有透過該 API 傳送追蹤資料。不過，您的專案可能會包含追蹤資料。舉例來說，某些 Google Cloud 服務 (例如 App Engine 標準環境、Cloud Run 函式和 Cloud Run) 會將追蹤記錄資料傳送至您的專案，但不會使用 Cloud Trace API。

   如果應用程式透過 Cloud Trace API 傳送追蹤記錄資料，且要求資料欄為零，請檢查應用程式和 Proxy，確認這些項目已設定為將追蹤記錄傳送至正確的專案。

4. 如果標示為「Error」的資料欄列出非零值，表示讀取或寫入追蹤記錄資料時發生錯誤。如要進一步瞭解錯誤來源，請依序選取「Cloud Trace API」和「指標」分頁，然後找出標示為「Errors by API method」的圖表：

   • 如果寫入作業失敗，請將 Cloud Trace 代理人角色 (roles/cloudtrace.agent) 授予提供驗證憑證的服務帳戶。這個角色包含 cloudtrace.traces.patch 權限，可讓應用程式將跨區資料寫入 Google Cloud 專案。

     詳情請參閱 Cloud Trace IAM 角色。

   • 如果讀取作業失敗，請確認您在 Google Cloud 專案中的 IAM 角色包含 Cloud Trace 使用者角色 (roles/cloutrace.user) 中的權限。如需此角色的權限清單，請參閱「Cloud Trace IAM 角色」。

5. 確認「Trace Explorer」頁面是否正在搜尋目前專案的追蹤記錄資料：

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

      前往「Trace Explorer」頁面

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

   2. 在工具列中前往「Scope」元素，展開「Refine scope」選單，選取「Current project」，然後選取「Apply」。

6. 請嘗試下列任一做法：

   • 切換至舊版「Trace Explorer」頁面。這個頁面會從與 Trace Explorer 頁面不同的資料庫讀取追蹤和跨度資料。

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

   • 使用 Cloud Trace API 將跨度傳送至 Google Cloud 專案。詳情請參閱「強制建立 Trace Explorer 頁面資料庫」一文。

搜尋特定追蹤記錄失敗

您可以在「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 天或更大的值時，系統不會顯示較舊的資料。

「Trace Explorer」頁面不會顯示超過 Cloud Trace 資料保留期限 (30 天) 的時間範圍資料。

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

如要查看及分析舊版追蹤記錄資料，請切換至舊版「Trace Explorer」頁面。這個頁面會從與 Trace Explorer 頁面不同的資料庫讀取追蹤和跨度資料。

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

追蹤記錄中缺少區間

您開啟「Trace Explorer」頁面，然後選取要查看的區間。「Details」彈出式視窗會顯示追蹤記錄，但缺少部分區間。

缺少跨度的可能原因如下：

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

• 您在 Google Cloud 專案中扮演的 IAM 角色，儲存追蹤記錄的跨區資料，但不包含查看追蹤記錄資料所需的權限。

• 有檢測問題。例如，只有追蹤記錄中的部分區間會傳送至您的 Google Cloud 專案。

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

1. 在舊版「Trace Explorer」頁面中判斷追蹤記錄是否完成：

   1. 從追蹤記錄的「Details」彈出式視窗，將追蹤 ID 複製到剪貼簿。

   2. 前往舊版「Trace Explorer」頁面：

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

   3. 將追蹤記錄 ID 貼到「追蹤記錄 ID」欄位。

      「Trace details」頁面會更新，並列出儲存追蹤記錄時距的專案。

2. 如果追蹤記錄在舊版「Trace 探索工具」頁面中完成，請返回「Trace 探索工具」頁面，並將「範圍」元素設為追蹤記錄範圍，列出您在上一個步驟中識別的所有專案。這些是儲存所選追蹤記錄時距的專案。

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

3. 如果追蹤記錄在舊版「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.

如要解決這則訊息，請在工具列中執行下列操作：

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

強制建立「Trace Explorer」頁面的資料庫

如果專案中唯一的追蹤記錄資料來自為 Cloud Trace 預先設定的 Google Cloud 服務，則「Trace 探索工具」頁面可能不會為追蹤記錄和時距資料讀取資料庫。不過，您可以使用 Cloud Trace API 將追蹤記錄傳送至專案，強制建立這個資料庫。 Google Cloud

舉例來說，您可以執行下列操作：

1. 前往 patchTraces 說明文件頁面。

2. 在「試試這個方法」窗格中，執行下列操作：

   1. 在「projectId」projectId欄位中輸入 PROJECT_ID。

   2. 將定義單一跨度的追蹤記錄的 JSON 複製到剪貼簿，然後貼到「Request body」(請求主體) 欄位中。

      複製 JSON 之前，請先執行下列操作：

      • 將 PROJECT_ID 替換為專案 ID。

      • 將 END_TIME 替換為目前時間，並將 START_TIME 替換為比結束時間早的值。如果您使用的是 Linux，請執行 date -Isec，以正確格式取得目前時間。例如，您可以將這些欄位設為以下格式：

        "startTime": "2024-05-31T15:10:35.398448Z",
        "endTime": "2024-05-31T15:10:35.574999047Z",
        

      • 每次執行指令時，請更新 traceId 和 spanId 欄位。

        "traces": [
          {
            "projectId": "PROJECT_ID",
            "traceId": "33fc0d8c45bb4e5cebb29f047931270d",
            "spans": [
              {
                "spanId": "17941747227541407973",
                "name": "/",
                "startTime": "START_TIME",
                "endTime": "END_TIME",
              }
            ]
          }
        ]
        

   3. 按下「執行」。

      指令順利完成後，回應主體會是空白。您可以前往「Trace Explorer」查看追蹤記錄。您可能需要稍候一段時間，系統才會在 Google Cloud 主控台中提供追蹤記錄。

排解舊版「Trace Explorer」頁面問題

本節說明使用舊版 Trace Explorer 頁面時，如何排解問題。

舊版介面中沒有資料

您使用的是舊版「Trace 探索工具」頁面，且在您預期會顯示追蹤記錄資料時，無法在 Google Cloud 專案中查看任何追蹤記錄。

如要解決這項失敗問題，請嘗試下列步驟：

1. Enable the Cloud Trace API.

   Enable the API

2. 在 Google Cloud 控制台中，前往「API 和服務」頁面：

   前往「API 和服務」頁面

   找到標示為「Cloud Trace API」的資料列後，請嘗試以下操作：

   • 如果標示為「Requests」的資料欄未列出任何數值資訊，就表示沒有任何追蹤記錄資料傳送至您的 Google Cloud 專案。

     如要解決這種情況，請檢查應用程式和 Proxy，確認設定可將追蹤記錄傳送至正確的專案。

   • 選取「Cloud Trace API」和「指標」分頁，然後找出標示為「Errors by API method」的圖表：

     • 如果寫入作業失敗，請將 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 將資料傳送至 Google Cloud 專案，但系統並未收集追蹤記錄資料。

建議您嘗試下列做法：

• 如果您在 Google Cloud 控制台的舊版「Trace Explorer」頁面中未看到任何資料，請按照「舊版 Trace 介面中沒有資料」一節中的步驟操作。

• 如果應用程式未部署在 Google Cloud 上，或是使用服務帳戶提供驗證憑證，請確認服務帳戶已獲得 Cloud Trace 代理人角色 (roles/cloudtrace.agent)。

  這個角色包含 cloudtrace.traces.patch 權限，可讓應用程式將跨區資料寫入 Google Cloud 專案。

• 如果應用程式依賴 OpenTelemetry，請執行下列操作：

  • 針對根服務，請嘗試更新環境變數，讓 OpenTelemetry 使用 traceidratio 取樣器，並設定 0.5 的取樣率：

    export OTEL_TRACES_SAMPLER="traceidratio"
    export OTEL_TRACES_SAMPLER_ARG="0.5"
    

  • 對於所有其他服務，請保留未設定的 OTEL_TRACES_SAMPLER 環境變數，以便使用預設取樣器 (parentbased_always_on)。預設設定表示，如果有此區間，則該區間的取樣決定會繼承自其父區間。如果父項區間不存在，則會對區間進行取樣。

  除非應用程式一律對每個區間進行取樣，否則一般來說，您無法強制要求進行端對端追蹤，因為端對端要求中的每個元件都會做出自己的取樣決策。不過，您可以將 sampled 標記新增至追蹤記錄標頭，並將此標記設為 true，藉此影響決定。這項設定是給子元件的提示，用於取樣要求。如要進一步瞭解追蹤標頭，請參閱「用於傳播內容的通訊協定」。

追蹤記錄中缺少跨度 ID 訊息

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

在分散式追蹤系統中，追蹤記錄可能不完整。如果取樣區段包含未收到的另一個區段參照，則追蹤記錄不完整。未解析的參照項目可能會發生以下情況：

• 未對參照的區間進行取樣。
• 系統已對參照的時距進行取樣，但 Cloud Trace 尚未收到，或是系統已收到時距，但未儲存。

當您查看不完整的追蹤記錄時，Cloud Trace 會在追蹤記錄詳細資料窗格中顯示「Missing span ID」(缺少時距 ID) 訊息。

如果您一再看到「缺少 span ID」訊息，請嘗試以下操作：

• 針對您管理的元件，請確保在這個欄位存在時，元件會遵循並傳播標頭的 sampled 標記。這項設定是給子元件的提示，用於取樣要求。如要進一步瞭解追蹤標頭，請參閱「用於傳播內容的通訊協定」。

  Google Cloud 服務通常會遵循這個提示。不過，它們也會限制記錄資料的寫入速率。

• 如果您使用的是 Cloud Service Mesh，請務必按照指示為這些設定傳播追蹤記錄內容。如需 Cloud Service Mesh 指引，請參閱「追蹤內容傳播」。

更新 Go 應用程式以使用 OpenTelemetry 後，沒有追蹤記錄資料

您的應用程式會使用用戶端程式庫擷取追蹤記錄，但在更新應用程式以使用 OpenTelemetry 後，您就不會再看到 Cloud Trace 資料。

由於部分 Go 適用的 Cloud 用戶端程式庫已與 OpenCensus 整合，因此您必須使用 OpenCensus Bridge。如要進一步瞭解橋接解決的問題，請參閱 OpenCensus Bridge。

如要瞭解 Go 適用的 Cloud 用戶端程式庫更新，請參閱 問題 #4237。