檢測 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 上執行的應用程式，可以使用 Ops Agent 和 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：

建立自訂 Span

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

您也可以在現有的 Span 中加入自訂註解和標記，藉此新增與應用程式相關的資訊，或是建立新的子 Span，並加入專屬的註解和標記，以更精細的方式追蹤應用程式的行為。

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

強制追蹤記錄取樣

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

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

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

使用範例建立指標和追蹤記錄之間的關聯

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

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

設定專案和平台

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

啟用 API

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

啟用 Telemetry 和 Cloud Trace API (如果尚未啟用)。

啟用 API 所需的角色

您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「Service Usage 管理員」角色 (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 寫入者角色 (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"

後續步驟