檢測 Cloud Trace

您可以檢測應用程式以使用 Cloud Trace 擷取分散式追蹤資料、檢查個別要求的延遲情況，以及在 Trace 控制台中查看服務的匯總延遲情況。

本文將概略說明插碼方法和設定選項。如需特定程式設計語言的逐步操作說明，請參閱該語言的設定頁面。

檢測應用程式的時機

如果系統未自動擷取用於驗證效能或排解問題的追蹤資料，請為應用程式進行儀表化。

為應用程式加入檢測功能，收集特定資訊，瞭解應用程式的效能並排解失敗問題。多個開放原始碼檢測架構會收集記錄、指標和追蹤記錄資料，並將資料傳送給任何供應商，包括 Google Cloud。對於代理程式應用程式，部分架構可能會收集提示和回覆，或傳遞可追蹤部分遠端 Google Cloud MCP 伺服器呼叫的內容。

如要檢測應用程式，建議您使用開放原始碼、與供應商無關的檢測架構 (例如 OpenTelemetry)，而非供應商和產品專屬的 API 或用戶端程式庫。如要瞭解這些架構，請參閱「 檢測和觀測能力」和「選擇檢測方法」。

如何檢測應用程式

您可以使用幾種方法來檢測應用程式：

  • 建議做法：使用 OpenTelemetry，透過 OTLP 匯出工具設定應用程式，將追蹤資料傳送至收集器，並設定收集器，使用 Telemetry (OTLP) API 將追蹤資料傳送至 Google Cloud 專案。如要進一步瞭解最佳化建議，請參閱「選擇插碼方法」。

  • 使用 OpenTelemetry，並透過 OTLP 匯出工具設定應用程式，使用 Telemetry API 將追蹤記錄資料傳送至 Google Cloud 專案。

  • 如果您編寫在 Compute Engine 上執行的應用程式，可以使用作業套件代理程式和 OpenTelemetry Protocol (OTLP) 接收器，從應用程式收集追蹤記錄和指標。Ops Agent 也可以收集記錄，但不是使用 OTLP。詳情請參閱「使用 Ops Agent 和 OTLP」和「Ops Agent 總覽」。

  • 直接叫用 Telemetry API 或 Cloud Trace API。

  • 如果是 Spring Boot 應用程式，請設定將收集到的追蹤資料轉送至 Cloud Trace。如要瞭解這項程序，請參閱 Spring Cloud for Google Cloud：Cloud Trace。

  • 使用 Cloud Trace 用戶端程式庫，或使用 OpenTelemetry 的 Cloud Trace 匯出工具。

檢測設備樣本

我們提供的檢測範例使用 OpenTelemetry：

建立自訂範圍

雖然 OpenTelemetry 和用戶端程式庫可讓您建立自訂時距，但您可能不需要手動建立，因為這些程式庫會在 RPC 邊界自動建立時距。

您也可以在現有 span 中新增自訂註解和標記，加入與應用程式相關的資訊，或是建立新的子項 span，並加上自己的註解和標記，以更精細的粒度追蹤應用程式的行為。

程式庫通常會維護全域追蹤內容，其中包含目前範圍的相關資訊，包括追蹤 ID 和取樣狀態。應用程式可以透過全域追蹤內容存取目前的範圍。由於環境是全域的，請確保多執行緒應用程式會在執行緒間傳播環境，以維持準確的追蹤資料。

強制追蹤記錄取樣

您無法強制取樣跨度，因為要求路徑中的每個元件都會獨立做出取樣決策。不過，您可以在追蹤記錄標頭中將 sampled 旗標設為 true，藉此影響下游元件。這項設定會提示子元件對要求進行取樣。 如要進一步瞭解追蹤記錄標頭，請參閱「環境傳播通訊協定」。

  • 您的應用程式：您可以設定插碼邏輯如何遵守 sampled 旗標。舉例來說，使用 OpenTelemetry 時，您可以利用 ParentBased 取樣器確保系統會遵守父項的取樣旗標。

  • Google Cloud 服務：每項服務都會決定自己的追蹤支援。一般來說，服務會接受父項取樣標記做為提示，同時強制執行本身的取樣率限制。

根據範例找出指標和追蹤記錄的關聯

您可以使用範例將指標資料與追蹤記錄建立關聯。樣本是與指標評估相關聯的代表性樣本要求或範圍。舉例來說，範例可以包含追蹤記錄的連結，方便您將指標和追蹤記錄資料相互關聯。如需以 OpenTelemetry 為基礎的範例，請參閱「使用樣本關聯指標和追蹤記錄」。

如果資訊主頁圖表顯示追蹤資料的 SQL 查詢結果，您可能會看到系統產生的範例。這些範例會將特定查詢結果直接連結至追蹤記錄。詳情請參閱「產生及顯示追蹤範例」。

設定專案和平台

本節說明必要的 API 和 Identity and Access Management (IAM) 角色，並說明如何為平台設定驗證憑證。

啟用 API

根據預設， Google Cloud 專案會啟用 Cloud Trace API 和 Telemetry API，您不必採取任何行動。不過，貴機構定義的安全性限制可能會停用其中一項或兩項 API。如需疑難排解資訊，請參閱「在受限的 Google Cloud 環境中開發應用程式」。

啟用 Telemetry 和 Cloud Trace API。

啟用 API 時所需的角色

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

啟用 API

授予 IAM 角色

您必須具備的 IAM 角色取決於您是在 Google Cloud 控制台中查看追蹤記錄資料，還是將追蹤記錄資料寫入專案：

  • 如要取得使用 Google Cloud 控制台查看追蹤資料所需的權限，請要求管理員授予您專案的「Cloud Trace 使用者」 (roles/cloudtrace.user) IAM 角色。

  • 如要取得使用 Cloud Trace API 寫入追蹤資料所需的權限，請要求管理員授予您專案的「Cloud Trace 代理程式」(roles/cloudtrace.agent) IAM 角色。

  • 如要取得使用 Telemetry API 寫入追蹤資料所需的權限，請要求管理員授予您專案的「Cloud Telemetry Writer」角色 (roles/telemetry.writer) IAM 角色。

驗證

本節說明應用程式在Google Cloud 上執行時，以及在其他位置執行時的驗證方式。

在 Google Cloud上執行

如果應用程式在 Google Cloud上執行，一般來說不需要提供驗證憑證。不過，即使是託管在 Google Cloud上的專案，部分語言用戶端程式庫仍需要專案 ID。

確認 Google Cloud 平台已啟用 Cloud Trace API 存取權範圍。對於下列設定，預設存取權範圍設定包含 Cloud Trace API 存取權範圍：

如果您使用自訂存取權範圍，請務必啟用 Cloud Trace API 存取權範圍。舉例來說，如果您使用 Google Cloud CLI 建立 GKE 叢集，並指定 --scopes 旗標，請務必確認範圍包含 trace.append。下列指令說明如何設定 --scopes 旗標：

gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

在本機及其他位置執行

如果應用程式在 Google Cloud以外的環境執行，您必須向用戶端程式庫提供驗證憑證。必須將 Cloud Trace 代理者角色 (roles/cloudtrace.agent) 授予服務帳戶。如要瞭解角色，請參閱「使用 IAM 控管存取權」。

Google Cloud 用戶端程式庫使用應用程式預設憑證 (ADC) 來尋找應用程式的憑證。您可以透過下列三種方式之一提供這些憑證：

  • 執行 gcloud auth application-default login

  • 將服務帳戶金鑰檔案放在作業系統的預設路徑中。以下列出 Windows 和 Linux 的預設路徑：

    • Windows：%APPDATA%/gcloud/application_default_credentials.json

    • Linux：$HOME/.config/gcloud/application_default_credentials.json

  • 將 GOOGLE_APPLICATION_CREDENTIALS 環境變數設為服務帳戶的路徑：

    Linux/macOS

        export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

    Windows

        set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

    PowerShell：

        $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

後續步驟