您可以檢測應用程式以使用 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：
如需使用以收集器為準的匯出範例，請參閱下列內容：
這些範例會使用 Telemetry API，將符合 OpenTelemetry Protocol (OTLP) 格式的指標和追蹤記錄資料傳送至專案。範例會使用記錄資料的 Google Cloud 匯出工具。
如要瞭解如何直接匯出追蹤資料，並將該資料傳送至 Telemetry API，請參閱「從 Trace 匯出工具遷移至 OTLP 端點」。
如需如何設定具備代理功能的應用程式來收集提示和回覆的範例，請參閱「如何為生成式 AI 應用程式進行儀表化」。
- 如要瞭解可產生追蹤範圍的 Google Cloud MCP 伺服器，請參閱「使用 Trace 檢查 MCP 呼叫」。
建立自訂範圍
雖然 OpenTelemetry 和用戶端程式庫可讓您建立自訂範圍， 但您可能不需要手動建立，因為這些程式庫會在 RPC 邊界自動建立範圍。
您也可以在現有範圍中新增自訂註解和標記，或建立新的子範圍，並加入自己的註解和標記，以更精細的粒度追蹤應用程式的行為，進一步瞭解應用程式。
程式庫通常會維護全域追蹤內容，其中包含目前範圍的相關資訊，包括追蹤 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) 取得這項權限。瞭解如何授予角色。
授予 IAM 角色
所需 IAM 角色取決於您是在 Google Cloud 控制台中查看追蹤記錄資料，還是將追蹤記錄資料寫入專案：
-
如要取得使用 Telemetry API 寫入追蹤資料所需的權限，請要求管理員授予您專案的「Cloud Telemetry Writer」角色 (
roles/telemetry.writer) IAM 角色。
驗證
本節說明應用程式在Google Cloud 上執行時，以及在其他位置執行時的驗證方式。
在 Google Cloud上執行
應用程式在 Google Cloud上執行時，一般不需要提供驗證憑證。不過，部分語言用戶端程式庫需要專案 ID，即使是託管在 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.jsonLinux：
$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"