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没有SDK部署实例的记录，并且无法在不接管整个资源的情况下将环境变量分层应用到该实例上。

如果您已经运行了agents-cli deploy，您有两个选择：

切换到Terraform管理。 删除SDK部署的Reasoning Engine，然后运行agents-cli infra single-project，接着运行agents-cli deploy。先前实例上的会话和任何进行中的状态将丢失。
保留SDK部署的实例。 跳过infra single-project，直接通过vertexai客户端的updateAPI在运行中的实例上设置可观测性环境变量。您还需要授予实例的服务账号发出遥测所需的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跨度展示执行流程、延迟、错误	所有模板，所有环境	始终启用	调试延迟，理解代理执行流程
提示-响应日志记录	GenAI交互导出到GCS、BigQuery和Cloud Logging	仅ADK代理	本地禁用，部署时启用	审计LLM交互，合规性
BigQuery Agent Analytics	结构化代理事件（LLM调用、工具使用、结果）到BigQuery	启用插件的ADK代理	选择加入（搭建时使用`--bq-analytics`）	对话分析，自定义仪表板，LLM作为评判者的评估
第三方集成	外部可观测性平台（AgentOps、Phoenix、MLflow等）	任何ADK代理	选择加入，按提供商设置	团队协作，专业可视化，提示管理

询问用户他们需要哪些层级——它们可以组合使用。Cloud Trace始终开启；其他层级是附加的。

Cloud Trace

ADK使用OpenTelemetry发出分布式追踪。每次代理调用都会生成跟踪完整执行流程的跨度。

跨度层次结构

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交互（模型名称、令牌、时间）并导出到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，跨度树可视化	中等（需要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`环境变量
第三方集成未捕获跨度	检查提供商特定的环境变量（API密钥、端点）；某些提供商（AgentOps）会替换原生遥测
追踪缺少工具跨度	工具执行跨度出现在`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`

你可能还喜欢

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

获取

cloud-design-patterns

37Kdevops-cloud

分布式系统架构的云设计模式，涵盖可靠性、性能、消息传递、安全性和部署等 5 大类共 42 种行业标准设计模式。适用于设计、评审或实现分布式系统架构等场景。

github

获取

deployment-pipeline-design

38Kdevops-cloud

设计包含审批门控、安全检查与部署编排的多阶段CI/CD流水线。在设计零停机部署流水线、实施金丝雀发布策略、设置多环境晋升工作流或调试CI/CD中失败的部署门控时使用此技能。

wshobson

获取

继续探索

浏览 devops-cloud 热门 Skills 最近更新

google-agents-cli-observability

相关 Skills