檢測 Cloud Trace

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

Cloud Trace 會為您的應用程式提供分散式追蹤資料。檢測應用程式後，您可以在 Cloud Trace 控制台中查看單一要求的延遲資料，以及整個應用程式的匯總延遲資料。

應用程式檢測時機

如果系統未自動擷取追蹤資料，您就必須對應用程式進行檢測，才能收集這類資料。

您可以設定應用程式，讓應用程式收集特定應用程式資訊。您可以使用多個開放原始碼檢測架構，從應用程式收集指標、記錄和追蹤記錄，並將這些資料傳送給任何供應商，包括 Google Cloud。如要檢測應用程式，建議您使用開放原始碼的供應商中立檢測架構，例如 OpenTelemetry，而非供應商和產品專屬的 API 或用戶端程式庫。

如要瞭解如何使用供應商中立的檢測架構來檢測應用程式，請參閱「 檢測和可觀察性」一文。

如何檢測應用程式

如要檢測應用程式以收集追蹤記錄資料，您可以執行下列任一操作：

建立跨度的時機

Cloud Trace 用戶端程式庫通常會維護全域追蹤記錄背景，其中保存目前跨度的相關資訊，包括追蹤記錄 ID 和是否對追蹤記錄進行取樣。這些程式庫通常會在 RPC 邊界上建立跨度。不過，如果預設建立演算法無法滿足需求，您可能需要建立跨度。

全域追蹤記錄背景資訊可存取目前的活動範圍，而這項資訊有時會包裝在 Tracer 物件中。您可以為現有的區間加上自訂註解和標記，藉此新增與應用程式相關的資訊，也可以建立新的子區間，並加上各自的註解和標記，以更精細的方式追蹤應用程式的行為。由於背景資訊是全域的，因此更新背景資訊的多執行緒應用程式必須使用適當的隔離功能。

何時應提供驗證憑證

一般來說，您在 Google Cloud上執行時，不需要為應用程式提供驗證憑證，也不需要在應用程式中指定 Google Cloud 專案 ID。對於某些語言，即使您是在 Google Cloud上執行，也需要指定 Google Cloud 專案 ID。此外，如果您使用 Google Kubernetes Engine 的 Autopilot 模式，或是啟用 GKE 適用的工作負載身分聯盟，則必須將應用程式設為使用 GKE 適用的工作負載身分聯盟。

如果您是在 Google Cloud以外執行，則需要為應用程式提供驗證憑證。您也必須在應用程式中指定Google Cloud 專案 ID。

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

如何強制追蹤要求

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

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

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

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

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

設定專案和平台

  1. 確認已啟用 Cloud Trace API。

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

    Enable the Cloud Trace API.

    Enable the 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 和其他開放原始碼存放區的連結，請前往所需語言的設定頁面。