檢測 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。

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

    Enable the Cloud Trace API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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