疑難排解

本文說明如何解決使用 Cloud Trace 時的常見問題，例如缺少 span 資料、Observability Analytics 中的查詢失敗，以及建立快訊政策時發生驗證錯誤。

已知問題

本節列出已知問題：

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

排解 Observability Analytics 問題

本節說明如何解決使用可觀測性分析查詢追蹤記錄資料時可能發生的失敗問題。

驗證錯誤，因此無法儲存警告政策

您嘗試儲存監控追蹤資料的警告政策，但收到類似以下的錯誤訊息：

The following error occurred when validating your SQL Alert: Error authenticating service account `[e-mail]`. BigQuery returned an error.

這則錯誤訊息表示系統尚未授予監控服務帳戶必要權限，或是該帳戶不存在。當使用者執行特定動作時，系統會自動建立這個帳戶。不過，如果 Cloud Monitoring API 已停用，系統就無法建立服務帳戶。

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

1. 在 Google Cloud 控制台中，前往「APIs & Services」(API 與服務) 頁面，然後啟用 Cloud Monitoring API：

   前往「API 與服務」頁面

2. 前往 Google Cloud 控制台的「IAM」頁面：

   前往 IAM

   如果您是使用搜尋列尋找這個頁面，請選取子標題為「IAM & Admin」(IAM 與管理) 的結果。

3. 在「IAM」頁面中，執行下列操作：

   1. 選取「包含 Google 提供的角色授權」。

   2. 如果未列出監控服務帳戶，請建立以 SQL 為基礎的警告政策，然後嘗試儲存該政策。

      儲存政策後，系統會建立監控服務帳戶。由於這個服務帳戶沒有必要的 IAM 角色，因此儲存動作會失敗。

   3. 將下列角色授予監控服務帳戶：

      • 專案中的監控服務代理程式 (roles/monitoring.notificationServiceAgent)。
      • 連結的 BigQuery 資料集中的「BigQuery 資料檢視者」圖示 (roles/bigquery.dataViewer) 。
      注意： 建議您限制追蹤資料連結的 BigQuery 資料集，只授予 BigQuery Data Viewer 角色。請勿在專案層級授予這個角色。

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

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

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

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

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

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

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

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

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

系統顯示「開始使用 Observability Analytics」訊息

您開啟「可觀測性分析」頁面，系統會顯示視窗，並顯示類似下列內容的訊息：

Get started with Observability Analytics

如要使用 Observability Analytics，請在視窗中按一下「關閉」。

如果沒有任何升級的記錄檔 bucket 可使用 Observability Analytics，系統就會顯示先前的訊息。不過，追蹤資料不會儲存在記錄檔 bucket 中。

無法彙整多個檢視區塊

您編寫的查詢會聯結多個檢視區塊，但查詢標示為無效。

並非所有檢視畫面都能加入。

如要加入檢視區塊，請注意下列限制：

1. 檢視區塊的位置符合下列其中一項條件：

   • 所有檢視區都有相同的位置。
   • 所有檢視畫面都位於 global 或 us 位置。

2. 如果儲存空間資源使用客戶自行管理的加密金鑰 (CMEK)，則必須符合下列其中一項條件：

   • 使用 CMEK 的儲存空間資源會使用相同的 Cloud KMS 金鑰。
   • 使用 CMEK 的儲存空間資源具有共同祖系，而該祖系會指定與儲存空間資源位於相同位置的預設 Cloud KMS 金鑰。

   當一或多個儲存空間資源使用 CMEK 時，系統會使用通用 Cloud KMS 金鑰或上層的預設 Cloud KMS 金鑰，加密聯結產生的暫時資料。

舉例來說，假設您有兩個位於相同位置的檢視區塊。接著，在符合下列任一條件時，即可聯結這些檢視畫面：

• 儲存空間資源未使用 CMEK。
• 一個儲存空間資源使用 CMEK，另一個則否。
• 兩個儲存空間資源都使用 CMEK，且都使用相同的 Cloud KMS 金鑰。

• 這兩項儲存空間資源都使用 CMEK，但使用的金鑰不同。不過，這些資源共用一個祖先，該祖先指定與儲存空間資源位於相同位置的預設 Cloud KMS 金鑰。

  舉例來說，假設記錄檔 bucket 和可觀測性 bucket 的資源階層包含相同機構。如果已為機構設定Cloud Logging 的預設資源設定，並為可觀測性 bucket 設定儲存位置的預設 Cloud KMS 金鑰，即可加入這些 bucket 的檢視畫面。

建立連結的 BigQuery 資料集時，因權限錯誤而失敗

您嘗試建立連結的 BigQuery 資料集，但作業失敗，並顯示類似下列的錯誤：

ERROR: (gcloud.beta.observability.buckets.datasets.links.create) {
  "code": 7,
  "message": "The caller does not have permission"
}

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

• 確認您已獲派必要的 IAM 角色。 如需這些角色的清單，請參閱「在資料集上建立連結」。

• 請查看貴機構的政策，判斷是否有適用於 BigQuery 資料集的限制。假設您建立自訂限制，規定 BigQuery 資料集必須位於特定位置。在這種情況下，您只能在位於該特定位置的可觀測性資料集上，建立連結的 BigQuery 資料集。

「Trace Explorer」頁面沒有資料

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

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

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

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

確認您有權查看追蹤資料

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

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

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

1. 啟用 Cloud Trace 和 Telemetry API。

   啟用 API 時所需的角色

   如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「服務使用情形管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

   啟用 API

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

   注意： 可能已有機構政策停用 Cloud Trace API。這些政策會禁止您啟用 API。

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

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

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

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

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

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

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

   • Cloud Trace API：Cloud Trace 代理程式角色 (roles/cloudtrace.agent)。
   • 遙測 API：Cloud Telemetry Trace Writer (roles/telemetry.tracesWriter)。

確認追蹤資料已儲存

追蹤記錄時距會儲存在名為 _Trace 的觀測能力值區中。當 Google Cloud 專案收到追蹤範圍時，系統會自動佈建該值區。不過，在某些情況下，佈建會失敗。

如要解決這項失敗問題，請嘗試下列其中一種做法：

• Google Cloud Play 管理中心操作說明：

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

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

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

1. 如果看到類似下方的橫幅，表示系統未佈建追蹤資料的儲存空間。 none {: .devsite-disable-click-to-copy} Trace storage is not initialized for this project. Enable trace storage to begin collecting trace data. 如要為追蹤資料佈建可觀測性 bucket，請前往橫幅並點選「啟用」。 按一下「啟用」後，系統會將範圍傳送至專案。系統收到範圍後，會發出指令來建立名為 _Trace 的可觀測性 bucket。這項程序可能需要幾分鐘才能完成。佈建完成後，系統會顯示通知橫幅，且 Cloud Trace 會擷取過去一小時內傳送的任何追蹤資料。資料可能需要幾分鐘的時間才會顯示在追蹤記錄探索工具中。如果沒有看到任何資料，請重新整理頁面。

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

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

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

• API 操作說明：

  1. 列出可觀測性值區。

  2. 如果專案沒有 _Trace 值區，請建立一個。

     詳情請參閱「建立可觀測性 bucket」。

搜尋特定追蹤記錄失敗

在「Trace Explorer」頁面中輸入追蹤記錄 ID。找不到追蹤記錄，且畫面會顯示類似以下的訊息：

The selected 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 Explorer 頁面，且可以查看近期資料，但將時間範圍選取器設為 30 天或更大的值時，系統不會顯示較舊的資料。

如果時間範圍超過 Cloud Trace 的資料保留期限 (30 天)，追蹤記錄探索器頁面就不會顯示資料。

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

顯示不完整的追蹤記錄

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

跨度可能因下列原因而遺失：

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

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

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

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

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

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

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

不支援跨區域查詢

您開啟「Trace Explorer」頁面，系統會顯示類似下列內容的訊息：

Error loading chart data. Cross-regional queries are not supported. The selected scope comprises buckets residing in multiple locations: list of locations.

錯誤訊息表示「追蹤記錄探索工具」頁面需要查詢儲存在不同位置的資料。

如要解決這項失敗問題，請採取下列任一做法：

• 將追蹤記錄資料限制為所選專案儲存的資料：

  • 前往「Trace Explorer」頁面的工具列，然後展開「Scope」選單。
  • 在「縮小範圍」飛出式選單中，選取「目前的專案」。

• 選取追蹤範圍，列出資料儲存在相同位置的專案。如要進行這項變更，請使用「範圍」選單中的選項。

• 從所選追蹤記錄範圍中，移除資料儲存在所選專案以外位置的專案：

  • 前往「Trace Explorer」頁面的工具列，然後展開「Scope」選單。
  • 在「縮小範圍」飛出式視窗中，選取「管理範圍」。
  • 您可以在「追蹤記錄範圍」頁面中編輯任何追蹤記錄範圍。

  如要找出追蹤記錄資料的儲存位置，請執行「列出可觀測性 bucket」指令。在路徑參數中指定專案，並將 LOCATION 欄位設為連字號 (-)，做為萬用字元。

追蹤記錄中缺少 span 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。