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`

您可能也喜歡

geofeed-tuner

38Kdevops-cloud

Use this skill whenever the user mentions IP geolocation feeds, RFC 8805, geofeeds, or wants help creating, tuning, validating, or publishing a self-published IP geolocation feed in CSV format. Intended user audience is a network operator, ISP, mobile carrier, cloud provider, hosting company, IXP, or satellite provider asking about IP geolocation accuracy, or geofeed authoring best practices. Helps create, refine, and improve CSV-format IP geolocation feeds with opinionated recommendations beyond RFC 8805 compliance. Do NOT use for private or internal IP address management — applies only to publicly routable IP addresses.

github

獲取

runtime

37Kdevops-cloud

@copilotkit/runtime — mount a fetch-native CopilotRuntime on any JS server, wire middleware, pick an AgentRunner, instantiate BuiltInAgent (Factory Mode with TanStack AI is the preferred default) or plug in any of 12 external agent frameworks (Mastra, LangGraph, CrewAI Crews/Flows, PydanticAI, ADK, LlamaIndex, Agno, AWS Strands, MS Agent Framework, AG2, A2A), enable Intelligence mode for durable threads + websocket, register server-side tools via defineTool, and wire voice transcription. Uses the fetch-based createCopilotRuntimeHandler primitive — the Express/Hono adapters are discouraged. Load the reference under references/ that matches your task.

copilotkit

獲取

deployment-pipeline-design

38Kdevops-cloud

設計多階段 CI/CD 管線，包含核准關卡、安全檢查與部署編排。當您需要設計零停機部署管線、實作金絲雀發布策略、設定多環境提升工作流程，或除錯 CI/CD 中失敗的部署關卡時，請使用此技能。

wshobson

獲取

繼續探索

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

google-agents-cli-observability

相關技能