google-agents-cli-observability

Name: google-agents-cli-observability
Author: google

ADK 可觀測性指南

Cloud Trace 開箱即用 — 無需基礎架構。提示-回應記錄和 BigQuery Agent Analytics 需要透過 Terraform 佈建的基礎架構（服務帳戶、GCS 儲存桶、BigQuery 資料集）。執行 agents-cli infra single-project --project PROJECT_ID 來佈建這些資源。詳情、環境變數和驗證指令請參閱 references/cloud-trace-and-logging.md。如果您的專案尚未建立脚手架，請先參閱 /google-agents-cli-scaffold。

`agent_runtime` 部署的操作順序

對於 deployment_target = agent_runtime，請在首次 agents-cli deploy 之前執行 agents-cli infra single-project。Terraform 模組擁有整個 Reasoning Engine 資源（display_name、服務帳戶、部署規格、環境變數），因此在 SDK 部署後才套用 Terraform 會導致狀態不一致 — Terraform 沒有 SDK 部署實例的記錄，也無法在不接管整個資源的情況下將環境變數疊加其上。

如果您已經執行過 agents-cli deploy，有兩個選項：

切換為 Terraform 管理。 刪除 SDK 部署的 Reasoning Engine，然後執行 agents-cli infra single-project 接著 agents-cli deploy。先前實例的工作階段和任何進行中的狀態將會遺失。
保留 SDK 部署的實例。 跳過 infra single-project，直接透過 vertexai 用戶端 update API 在執行中的實例上設定可觀測性環境變數。您還需要授予實例的服務帳戶發出遙測所需的 IAM 權限 — 寫入記錄 GCS 儲存桶、BigQuery 資料集存取、記錄寫入器等。請參閱已建立脚手架專案中的 deployment/terraform/single-project/iam.tf 和 telemetry.tf，以了解 Terraform 模組原本會佈建的所有繫結。在此模式下無法使用 Terraform 管理的環境變數。

參考檔案

檔案	內容
`references/cloud-trace-and-logging.md`	已建立脚手架專案詳情 — Terraform 佈建資源、環境變數、驗證指令、在本機啟用/停用
`references/bigquery-agent-analytics.md`	BQ Agent Analytics 外掛 — 啟用、主要功能、GCS 卸載、工具來源

可觀測性層級

根據您的需求選擇合適的可觀測性層級：

層級	功能	範圍	預設狀態	最適合
Cloud Trace	分散式追蹤 — 透過 OpenTelemetry span 呈現執行流程、延遲、錯誤	所有範本、所有環境	永遠啟用	偵錯延遲、了解代理程式執行流程
提示-回應記錄	GenAI 互動匯出至 GCS、BigQuery 和 Cloud Logging	僅限 ADK 代理程式	本機停用，部署時啟用	稽核 LLM 互動、合規
BigQuery Agent Analytics	結構化代理程式事件（LLM 呼叫、工具使用、結果）至 BigQuery	已啟用外掛的 ADK 代理程式	選擇加入（建立脚手架時使用 `--bq-analytics`）	對話分析、自訂儀表板、LLM-as-judge 評估
第三方整合	外部可觀測性平台（AgentOps、Phoenix、MLflow 等）	任何 ADK 代理程式	選擇加入，依供應商設定	團隊協作、專業視覺化、提示管理

詢問使用者需要哪些層級 — 它們可以組合使用。Cloud Trace 永遠開啟；其他層級為附加功能。

Cloud Trace

ADK 使用 OpenTelemetry 發出分散式追蹤。每次代理程式呼叫都會產生 span，追蹤完整的執行流程。

Span 層級結構

invocation
  └── agent_run（鏈中每個代理程式一個）
        ├── call_llm（模型請求/回應）
        └── execute_tool（工具執行）

依部署類型設定

部署	設定
Agent Runtime	自動 — 預設會將追蹤匯出至 Cloud Trace
Cloud Run（已建立脚手架）	自動 — FastAPI 應用程式中 `otel_to_cloud=True`
GKE（已建立脚手架）	自動 — FastAPI 應用程式中 `otel_to_cloud=True`
Cloud Run / GKE（手動）	在應用程式中設定 OpenTelemetry 匯出器
本機開發	可搭配 `agents-cli playground` 使用；追蹤可在 Cloud Console 中檢視

檢視追蹤：Cloud Console → Trace → Trace explorer

如需詳細設定說明（Agent Runtime CLI/SDK、Cloud Run、自訂部署），請擷取 https://adk.dev/integrations/cloud-trace/index.md。

提示-回應記錄

擷取 GenAI 互動（模型名稱、Token、時間）並匯出至 GCS（JSONL）和 BigQuery（透過直接記錄接收器和外部資料表）。預設保護隱私 — 除非明確設定，否則僅記錄中繼資料。

關鍵環境變數：OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT — OTel GenAI 語義慣例標準（模式：span_only、event_only、span_and_event、no_content）。已建立脚手架專案的 setup_telemetry() 會將所有非 false 的值縮減為 NO_CONTENT（僅中繼資料）；false 則停用擷取。除非設定了 LOGS_BUCKET_NAME，否則本機停用記錄。

已建立脚手架專案的詳細資訊（Terraform 資源、環境變數、隱私模式、啟用/停用、驗證指令），請參閱 references/cloud-trace-and-logging.md。

如需 ADK 記錄文件（記錄層級、設定、偵錯），請擷取 https://adk.dev/observability/logging/index.md。

BigQuery Agent Analytics 外掛

選用外掛，可將結構化代理程式事件記錄至 BigQuery。在建立脚手架時使用 --bq-analytics 啟用。詳情請參閱 references/bigquery-agent-analytics.md。

第三方整合

ADK 支援多個第三方可觀測性平台。每個平台使用 OpenTelemetry 或自訂檢測來擷取代理程式行為。

平台	主要差異	設定複雜度	自託管選項
AgentOps	工作階段重播、2 行程式碼設定、取代原生遙測	最低	否（SaaS）
Arize AX	商業平台、正式環境監控、評估儀表板	低	否（SaaS）
Phoenix	開源、自訂評估器、實驗測試	低	是
MLflow	OTel 追蹤至 MLflow Tracking Server、span 樹狀視覺化	中等（需要 SQL 後端）	是
Monocle	1 次呼叫設定、VS Code 甘特圖視覺化工具	最低	是（本機檔案）
Weave	W&B 平台、團隊協作、時間軸檢視	低	否（SaaS）
Freeplay	提示管理 + 評估 + 可觀測性於一體	低	否（SaaS）

詢問使用者偏好哪個平台 — 說明取捨並讓他們選擇。如需設定詳細資訊，請從下方深入探討表格中擷取相關的 ADK 文件頁面。

問題排除

問題	解決方案
Cloud Trace 中沒有追蹤	確認 FastAPI 應用程式中 `otel_to_cloud=True`；檢查服務帳戶是否具有 `cloudtrace.agent` 角色
提示-回應資料未出現	檢查是否設定了 `LOGS_BUCKET_NAME`；確認服務帳戶對儲存桶具有 `storage.objectCreator` 權限；檢查應用程式記錄中是否有遙測設定警告
隱私模式設定錯誤	檢查 `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` 值 — 僅中繼資料使用 `NO_CONTENT`，停用使用 `false`
BigQuery Analytics 未記錄	確認外掛已在 `app/agent.py` 中設定；檢查是否設定了 `BQ_ANALYTICS_DATASET_ID` 環境變數
第三方整合未擷取 span	檢查供應商特定的環境變數（API 金鑰、端點）；某些供應商（如 AgentOps）會取代原生遙測
追蹤缺少工具 span	工具執行 span 會出現在 `execute_tool` 下 — 檢查追蹤瀏覽器篩選條件
遙測成本過高	切換至 `NO_CONTENT` 模式；縮短 BigQuery 保留期；停用未使用的層級

深入探討：ADK 文件（WebFetch URL）

如需本技能未涵蓋的詳細文件，請擷取以下頁面：

主題	URL
可觀測性總覽	`https://adk.dev/observability/index.md`
代理程式活動記錄	`https://adk.dev/observability/logging/index.md`
Cloud Trace 整合	`https://adk.dev/integrations/cloud-trace/index.md`
BigQuery Agent Analytics	`https://adk.dev/integrations/bigquery-agent-analytics/index.md`
AgentOps	`https://adk.dev/integrations/agentops/index.md`
Arize AX	`https://adk.dev/integrations/arize-ax/index.md`
Phoenix (Arize)	`https://adk.dev/integrations/phoenix/index.md`
MLflow 追蹤	`https://adk.dev/integrations/mlflow-tracing/index.md`
Monocle	`https://adk.dev/integrations/monocle/index.md`
W&B Weave	`https://adk.dev/integrations/weave/index.md`
Freeplay	`https://adk.dev/integrations/freeplay/index.md`

您可能也喜歡

import-infrastructure-as-code

37Kdevops-cloud

Import existing Azure resources into Terraform using Azure CLI discovery and Azure Verified Modules (AVM). Use when asked to reverse-engineer live Azure infrastructure, generate Infrastructure as Code from existing subscriptions/resource groups/resource IDs, map dependencies, derive exact import addresses from downloaded module source, prevent configuration drift, and produce AVM-based Terraform files ready for validation and planning across any Azure resource type.

github

獲取

sandbox-sdk

2Kdevops-cloud

建立沙箱應用程式以安全執行程式碼。當建置 AI 程式碼執行、程式碼直譯器、CI/CD 系統、互動式開發環境或執行不受信任的程式碼時載入。涵蓋 Sandbox SDK 生命週期、指令、檔案、程式碼直譯器和預覽網址。傾向從 Cloudflare 文件檢索而非預先訓練的知識。

cloudflare

獲取

deployment-patterns

230Kdevops-cloud

Deployment workflows, CI/CD pipeline patterns, Docker containerization, health checks, rollback strategies, and production readiness checklists for web applications.

affaan-m

獲取

繼續探索

瀏覽 devops-cloud 熱門 Skills 最近更新

google-agents-cli-observability

相關技能