檢測 Cloud Trace

本文將簡要說明如何檢測應用程式以使用 Cloud Trace。如需設定 Cloud Trace 的詳細操作說明，請參閱各語言的設定頁面。

Cloud Trace 可提供應用程式的分散式追蹤資料。完成應用程式的檢測後，您可以在 Cloud 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。

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

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

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

  • 如需使用以收集器為準的匯出作業的範例，請參閱下列內容：

    這些範例會將追蹤資料傳送至 Telemetry API。

  • 如要瞭解如何直接匯出追蹤資料，並將該資料傳送至 Telemetry API，請參閱「從 Trace 匯出工具遷移至 OTLP 端點」。

  • 如需範例，瞭解如何設定具備代理功能的應用程式來收集提示和回覆，請參閱「如何檢測生成式 AI 應用程式」。

  • 如要瞭解哪些遠端 Google Cloud MCP 伺服器支援追蹤記錄產生功能，以及如何設定應用程式，指示這些伺服器建立時距，請參閱「使用 Trace 檢查 MCP 呼叫」。

建立範圍的時機

Cloud Trace 用戶端程式庫通常會維護全域追蹤記錄內容，其中包含目前時距的相關資訊，包括追蹤記錄 ID 和追蹤記錄是否經過取樣。這些程式庫通常會在 RPC 邊界建立範圍。不過，如果預設的建立演算法不符合需求，您可能需要建立範圍。

您可以透過全域追蹤內容存取目前作用中的範圍，有時這會包裝在 Tracer 物件中。您可以透過自訂註解和標記，將與應用程式相關的資訊新增至現有時距，也可以建立新的子時距，並使用自己的註解和標記追蹤應用程式行為，取得更精細的資料。由於背景資訊是全域的，因此更新背景資訊的多執行緒應用程式必須使用適當的隔離機制。

何時提供驗證憑證

在 Google Cloud上執行時，您通常不需要向應用程式提供驗證憑證，也不需要在應用程式中指定 Google Cloud 專案 ID。在某些語言中，即使您在 Google Cloud上執行，仍須指定 Google Cloud 專案 ID。此外，如果您使用 Google Kubernetes Engine 的 Autopilot 模式，或是啟用 Workload Identity Federation for GKE，則必須將應用程式設定為使用 Workload Identity Federation for GKE。

如果您在 Google Cloud以外的環境執行，請為應用程式提供驗證憑證。您也需要在應用程式中指定Google Cloud 專案 ID。

詳情請參閱各語言的設定頁面。

如何強制追蹤要求

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

如果是您擁有的下游元件程式碼，請務必判斷檢測邏輯是否遵守 sampled 旗標。舉例來說，使用 OpenTelemetry 進行檢測時，您可以運用 ParentBased 取樣器，確保系統會遵守父項取樣旗標。

Google Cloud 將追蹤資訊記錄到 Cloud Trace 的服務通常會接受父項取樣標記做為提示，但大多數服務也會限制取樣率。各 Google Cloud 服務 會判斷是否支援追蹤、如何使用父項取樣標記，以及取樣的速率限制。

如何關聯指標和追蹤記錄資料

您可以將樣本附加至指標資料點，將分布值指標資料與追蹤記錄建立關聯。只要完成必要的設定步驟，建議使用的檢測程式庫 OpenTelemetry 就會自動新增這些範例。詳情請參閱「使用範例關聯指標和追蹤記錄」。

設定專案和平台

  1. 確認已啟用 Cloud Trace API。

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

    啟用 Cloud Trace API。

    啟用 API 時所需的角色

    如要啟用 API，您需要服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

    啟用 API

  2. 設定平台。

    您可以在 Google Cloud 和其他平台上使用 Cloud Trace。

    • Google Cloud：應用程式在Google Cloud上執行時，您不需要以服務帳戶的形式，向用戶端程式庫提供驗證憑證。不過，請務必確認您的 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"

後續步驟

如需詳細的設定資訊、範例，以及 GitHub 和其他開放原始碼存放區的連結，請前往您所用語言的設定頁面。