adk-observability-guide

ADK 可观测性指南

通过脚手架生成的项目？ Cloud Trace 和提示词-响应日志记录已由 Terraform 预先配置。基础设施详情、环境变量和验证命令请参阅 references/cloud-trace-and-logging.md。

未使用脚手架？ 请按照下方 ADK 文档链接手动设置。对于生产环境基础设施，请使用 /adk-scaffold 生成脚手架。

参考文件

文件	内容
references/cloud-trace-and-logging.md	通过脚手架生成的项目详情 — Terraform 配置的资源、环境变量、验证命令、本地启用/禁用方法
references/bigquery-agent-analytics.md	BQ Agent Analytics 插件 — 启用方法、主要功能、GCS 卸载、工具来源

---

可观测性层级

根据需求选择合适的可观测性级别：

层级	功能	范围	默认状态	适用场景
Cloud Trace	分布式追踪 — 通过 OpenTelemetry spans 跟踪执行流程、延迟和错误	所有模板，所有环境	始终启用	调试延迟、了解 Agent 执行流程
提示词-响应日志记录	将 GenAI 交互导出到 GCS、BigQuery 和 Cloud Logging	仅限 ADK Agent	本地禁用，部署后启用	审计 LLM 交互、合规
BigQuery Agent Analytics	将结构化 Agent 事件（LLM 调用、工具使用、结果）写入 BigQuery	启用了插件的 ADK Agent	选择启用（生成脚手架时使用 --bq-analytics）	对话分析、自定义仪表板、LLM-as-judge 评估
第三方集成	外部可观测性平台（AgentOps、Phoenix、MLflow 等）	任何 ADK Agent	选择启用，按提供商设置	团队协作、专业可视化、提示词管理

询问用户需要哪些层级 — 可以组合使用。Cloud Trace 始终启用；其他层级可叠加使用。

---

Cloud Trace

ADK 使用 OpenTelemetry 发出分布式追踪数据。每次 Agent 调用都会生成 spans，以跟踪完整的执行流程。

Span 层级

invocation
  └── agent_run (one per agent in the chain)
        ├── call_llm (model request/response)
        └── execute_tool (tool execution)

按部署类型设置

部署方式	设置
Agent Engine	自动 — 默认将追踪数据导出到 Cloud Trace
Cloud Run（通过脚手架生成）	自动 — FastAPI 应用中设有 otel_to_cloud=True
GKE（通过脚手架生成）	自动 — FastAPI 应用中设有 otel_to_cloud=True
Cloud Run / GKE（手动）	在应用中配置 OpenTelemetry 导出器
本地开发	可通过 make playground 使用；可在 Cloud Console 中查看追踪数据

查看追踪数据：Cloud Console → Trace → Trace explorer

如需详细设置说明（Agent Engine CLI/SDK、Cloud Run、自定义部署），请获取 https://adk.dev/integrations/cloud-trace/index.md。

---

提示词-响应日志记录

捕获 GenAI 交互（模型名称、令牌、耗时），并将其导出到 GCS（JSONL）、BigQuery（外部表）和 Cloud Logging（专用存储桶）。默认保护隐私 — 除非明确配置，否则仅记录元数据。

关键环境变量：OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT — 设置为 NO_CONTENT（仅元数据，在已部署环境中为默认值）、true（完整内容）或 false（禁用）。本地默认禁用日志记录，除非设置了 LOGS_BUCKET_NAME。

通过脚手架生成的项目详情（Terraform 资源、环境变量、隐私模式、启用/禁用方法、验证命令），请参阅 references/cloud-trace-and-logging.md。

如需 ADK 日志记录文档（日志级别、配置、调试），请获取 https://adk.dev/observability/logging/index.md。

---

BigQuery Agent Analytics 插件

用于将结构化 Agent 事件记录到 BigQuery 的可选插件。生成脚手架时使用 --bq-analytics 启用。详情请参阅 references/bigquery-agent-analytics.md。

---

第三方集成

ADK 支持多个第三方可观测性平台。每个平台都使用 OpenTelemetry 或自定义埋点来捕获 Agent 行为。

平台	主要差异	设置复杂度	可自托管选项
AgentOps	会话回放、只需 2 行代码即可设置、取代原生遥测	极低	否（SaaS）
Arize AX	商业平台、生产环境监控、评估仪表板	低	否（SaaS）
Phoenix	开源、自定义评估器、实验测试	低	是
MLflow	将 OTel 跟踪数据发送到 MLflow Tracking Server、可视化跨度树	中等（需要 SQL 后端）	是
Monocle	只需 1 次调用即可设置、VS Code 甘特图可视化工具	极低	是（本地文件）
Weave	W&B 平台、团队协作、时间线视图	低	否（SaaS）
Freeplay	在一个平台中整合提示词管理、评估和可观测性	低	否（SaaS）

询问用户偏好哪个平台——介绍各自的优缺点并让他们选择。有关设置详情，请从下方的深度指南表格中获取相应的 ADK 文档页面。

---

故障排除

问题	解决方案
Cloud Trace 中没有跟踪数据	确认 FastAPI 应用中设置了 otel_to_cloud=True；检查服务账号是否具有 cloudtrace.agent 角色
未显示提示词-响应数据	检查是否设置了 LOGS_BUCKET_NAME；确认 SA 对存储桶具有 storage.objectCreator 权限；检查应用日志中是否有遥测设置警告
隐私模式配置错误	检查 OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT 的值——仅记录元数据时使用 NO_CONTENT，禁用时使用 false
BigQuery Analytics 未记录日志	确认已在 app/agent.py 中配置插件；检查是否设置了 BQ_ANALYTICS_DATASET_ID 环境变量
第三方集成未捕获跨度	检查提供商专属环境变量（API 密钥、端点）；某些提供商（AgentOps）会取代原生遥测
跟踪数据中缺少工具跨度	工具执行跨度显示在 execute_tool 下——检查跟踪浏览器筛选条件
遥测成本过高	切换到 NO_CONTENT 模式；缩短 BigQuery 数据保留时间；禁用未使用的层级

---

深入了解：ADK 文档（WebFetch URL）

如需了解本技能未涵盖的详细文档，请获取以下页面：

主题	URL
可观测性概述	https://adk.dev/observability/index.md
Agent 活动日志记录	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/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