google-agents-cli-observability

可观测性指南

Cloud Trace 开箱即用，无需任何基础设施。提示词-响应日志记录和 BigQuery Agent Analytics 需要通过 Terraform 配置基础设施（服务账号、GCS 存储桶、BigQuery 数据集）。运行 agents-cli infra single-project --apply --project PROJECT_ID 以配置这些资源。Go 项目也会获得 BigQuery 遥测堆栈；提示词-响应日志记录背后的 GCS 完成内容上传，以及 BigQuery Agent Analytics 插件仅支持 Python。详情、环境变量和验证命令请参阅 references/cloud-trace-and-logging.md。如果项目尚未搭建，请先参阅 /google-agents-cli-scaffold。

部署顺序

是否要使用 Terraform 管理可观测性？	操作
否	直接运行 agents-cli deploy（适用于所有目标）。
是	先运行 agents-cli infra single-project --apply，然后运行 agents-cli deploy。

如果你已通过命令直接运行 agents-cli deploy： 之后不要应用 Terraform。对于 Gemini 平台中的 Agent Runtime，Terraform 管理整个引擎（服务账号、部署规范、环境变量），因此之后应用 Terraform 时，若不接管该资源，就无法协调状态。
你可以删除部署并重新开始，也可以保留通过 SDK 部署的实例——跳过 infra single-project，并通过重新运行 agents-cli deploy --update-env-vars "KEY=VALUE,..." 设置可观测性环境变量；deploy 会按显示名称匹配现有 Reasoning Engine，并就地更新，同时保留在 deploy 之外设置的环境变量。你还必须为其服务账号授予 Terraform 模块原本会配置的遥测 IAM 角色：roles/storage.admin（将完成内容写入日志存储桶）、roles/logging.logWriter、roles/cloudtrace.agent，以及在搭建时使用了 --bq-analytics 的情况下授予 roles/bigquery.dataOwner + roles/bigquery.jobUser。完整列表位于 deployment/terraform/single-project/iam.tf（来自 app_sa_roles）和 telemetry.tf。此模式下无法使用 Terraform 管理的环境变量。

参考文件

文件	内容
references/cloud-trace-and-logging.md	已搭建项目的详情——通过 Terraform 配置的资源、环境变量、验证命令、本地启用/禁用
references/bigquery-agent-analytics.md	BQ Agent Analytics 插件——启用方法、主要功能、GCS 卸载、工具来源
references/adk-docs.md	**ADK：**需要了解本技能之外的详情时，可获取的 adk.dev 页面
references/feedback-mechanism.md	添加用户反馈端点——请求模型、结构化日志记录、日志接收器 → BigQuery

---

可观测性层级

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

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

询问用户需要哪些层级（可组合使用）。Cloud Trace 始终启用；其他层级均为附加功能。

---

Cloud Trace

脚手架生成的 Agent 使用 OpenTelemetry 发出分布式跟踪信息。每次调用 Agent 都会生成多个 Span，用于追踪完整的执行流程。

Span 层级

ADK 项目。 这些是 ADK 的 Span 名称；其他框架会发出自己的名称（无论如何，generate_content 都来自共享的 google-genai instrumentor）。

invoke_workflow (top-level run)
  └── invoke_agent (one per agent in the chain)
        ├── call_llm (model request)
        │     └── generate_content (underlying GenAI model call)
        └── execute_tool (tool execution)

按部署类型设置

部署方式	设置
Agent Runtime	自动 — 启动时配置导出器，由 GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY 控制（由部署设置）；导出到 Cloud Trace/Logging，以及 Google Cloud 控制台中的 Agent Runtime 页面
Cloud Run / GKE（脚手架生成）	自动 — 启动时配置导出器，导出到 Cloud Trace/Logging
Cloud Run / GKE（手动）	在应用中配置 OpenTelemetry 导出器
本地开发	可与 agents-cli playground 配合使用；跟踪信息可在 Cloud Console 中查看

在应用启动时完成配置 — ADK Python： app/fast_api_app.py 中的 get_fast_api_app(otel_to_cloud=True)；ADK Go： observability.go 中的 setupObservability()；其他模板会调用各自的方法。详情请参阅 references/cloud-trace-and-logging.md。

查看跟踪信息：Cloud Console → Trace → Trace explorer

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

---

提示词-响应日志记录

捕获 GenAI 交互，并将其导出到 GCS（JSONL）和 BigQuery（通过日志接收器 + 外部表）。内容受两个相互独立的层级控制；Terraform 部署的最终默认值为：GCS/BigQuery 中包含完整内容，跟踪信息中不包含内容：

层级	捕获内容	控制方式	默认值（Terraform 部署）
GCS/BigQuery 补全内容	完整提示词/响应（提示词-响应日志记录功能）	OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK=upload + LOGS_BUCKET_NAME	开启 — 完整内容
跟踪 Span / Cloud Logging 事件	Span/事件内容	OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT（以及 ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false，仅限 ADK Python）	关闭 — NO_CONTENT

这两个层级相互独立：只要设置了上传变量，GCS/BigQuery 上传就会捕获完整内容，且不会遵循 OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT；该变量仅控制跟踪/事件层级。

ADK Python 将其作为 experimental-semconv 枚举读取：

• NO_CONTENT — Span/事件中不包含内容（脚手架生成的默认值）
• EVENT_ONLY — Cloud Logging 事件中包含内容
• SPAN_ONLY / SPAN_AND_EVENT — 跟踪 Span 中包含内容
• true / false — 无效；回退为 NO_CONTENT

ADK Go 将同一变量作为布尔值读取："1" 或 "true" 会捕获内容；其他所有值——包括上述枚举成员——都会省略内容。

完整机制（semconv opt-in、声明式 Terraform 配置、环境变量表、启用/停用方法、验证命令）请参阅 references/cloud-trace-and-logging.md。ADK 日志记录文档（日志级别、配置、调试）请获取 https://adk.dev/observability/logging/index.md。

---

BigQuery Agent Analytics 插件

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

---

第三方集成

许多第三方可观测性平台都可以接收 Agent 遥测数据（通过 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：**通过 https://adk.dev/integrations/<slug>/index.md 获取平台的设置页面（上表中各平台的 slug：agentops、arize-ax、phoenix、mlflow-tracing、monocle、weave、freeplay）；ADK 还有更多可观测性集成（Datadog、Galileo、LangWatch、Latitude、Future AGI、Respan、Zespan 等）——请访问 https://adk.dev/integrations/ 浏览完整的最新列表（选择 observability 主题）。在其他框架中，基于 OpenTelemetry 的平台仍然适用，但请遵循平台自己的设置文档。

---

故障排除

问题	解决方案
Cloud Trace 中没有跟踪数据	确认遥测设置在启动时运行，且 SA 具有 cloudtrace.agent 角色。ADK Python：fast_api_app.py 使用 get_fast_api_app(otel_to_cloud=True)；**ADK Go：**在 observability.go 中手动构建导出器。Agent Runtime 还会通过 GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY 控制是否启用此功能。
未显示提示词-响应数据	检查是否已设置 LOGS_BUCKET_NAME；确认 SA 在存储桶上具有 storage.objectCreator 权限；检查应用日志中是否有遥测设置警告
跟踪数据/事件中包含内容（不需要）	ADK Python：OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=NO_CONTENT 可避免在 Span/事件中包含内容。**ADK Go：**任何非 1/true 的值都可以，因此请取消设置或设为 false。注意：GCS/BigQuery 补全仍会捕获完整内容——如需停止此行为，请移除 LOGS_BUCKET_NAME/OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK（删除 service.tf 中的上传代码块）
BigQuery Analytics 未记录日志	**ADK Python：**确认已在 app/agent.py 中配置插件；检查是否已设置 BQ_ANALYTICS_DATASET_ID 环境变量
第三方集成未捕获 Span	检查特定提供商的环境变量（API 密钥、端点）；某些提供商（AgentOps）会替代原生遥测
跟踪数据缺少工具 Span	**ADK：**工具执行 Span 会显示在 execute_tool 下（其他框架使用各自的 Span 名称）——检查跟踪浏览器筛选条件
遥测成本高	关闭内容捕获（Python 中设为 NO_CONTENT，Go 中设为 false）；缩短 BigQuery 保留时间；停用未使用的层级

---

相关技能

• /google-agents-cli-deploy — 部署目标、CI/CD 流水线和生产工作流
• /google-agents-cli-workflow — 开发工作流、编码指南和操作规则
• /google-agents-cli-adk-code — 用于编写 Agent 代码的 ADK API 快速参考，涵盖 Python 和 Go