用途：为 ADK 智能体搭建可观测性，并在分析生产流量、调试智能体行为或优化性能前阅读。可观测性分为多个层级，可组合使用。Cloud Trace 始终开启，其余为增量能力。
主要能力： 一、Cloud Trace。基于 OpenTelemetry 发出分布式追踪，覆盖执行流程、延迟与错误。跨度层级为 invocation → agent_run（每个智能体一个）→ call_llm、execute_tool。Agent Engine 默认自动导出；脚手架化的 Cloud Run、GKE 在 FastAPI 应用中设置 otel_to_cloud=True 后自动启用；手动部署需自行配置 OTel 导出器。本地开发配合 make playground 可用，追踪在 Cloud Console → Trace → Trace explorer 查看。 二、提示-响应日志。捕获 GenAI 交互的模型名、token、耗时等，导出到 GCS（JSONL）、BigQuery（外部表）和 Cloud Logging。默认隐私保护，只记元数据。关键环境变量 OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT 取值 NO_CONTENT（仅元数据）、true（完整内容）、false（关闭）。本地未设置 LOGS_BUCKET_NAME 时日志关闭。 三、BigQuery Agent Analytics 插件。将结构化智能体事件（LLM 调用、工具使用、结果）写入 BigQuery，需在脚手架时加 --bq-analytics 启用，适合对话分析、自定义仪表盘与 LLM-as-judge 评测。 四、第三方集成。支持 AgentOps、Arize AX、Phoenix、MLflow、Monocle、Weave、Freeplay 等，各自用 OpenTelemetry 或自定义埋点，按提供商单独配置。
使用方式：先确定所需层级，再按部署类型配置。脚手架化的 Cloud Run 与 GKE 在 FastAPI 应用中设置 otel_to_cloud=True。详情可查阅参考文件 references/cloud-trace-and-logging.md、references/bigquery-agent-analytics.md，或按下表 URL 访问 ADK 文档。
适用场景：延迟调试、执行流程理解、LLM 交互审计与合规、对话分析、自定义仪表盘与评测、团队协作与提示管理。
限制与排错：无追踪时检查 otel_to_cloud=True 及服务账号 cloudtrace.agent 角色；日志缺失时检查 LOGS_BUCKET_NAME 与存储权限；BigQuery 未记录时检查插件配置与 BQ_ANALYTICS_DATASET_ID；第三方未捕获跨度时检查对应环境变量，部分提供商会替换原生遥测；成本过高时可改用 NO_CONTENT 模式或减少保留与层级。具体命令与更细的配置细节本资料未完整给出。