Agent Starter Pack 可观测性完全指南Cloud Trace 遥测与 BigQuery Agent Analytics 双方案实战【免费下载链接】agent-starter-packShip AI Agents to Google Cloud in minutes, not months. Production-ready templates with built-in CI/CD, evaluation, and observability.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-starter-packAgent Starter Pack 为所有生成的 Agent 项目内置了开箱即用的监控与可观测性能力覆盖执行链路追踪、LLM 交互日志、工具调用分析与成本优化四大场景。本文以官方文档《Monitoring and Observability》为核心系统讲解默认启用的 Cloud Trace 遥测与可选开启的 BigQuery Agent Analytics Plugin 两大方案并结合仓库源码说明其底层实现原理帮助你在本地开发与 Terraform 部署环境中快速落地、验证与排障。一、两大可观测性能力总览Agent Starter Pack 提供两套互补的可观测性方案见 docs/guide/observability/index.mdAgent Telemetry EventsCloud Trace基于 OpenTelemetry 的分布式追踪能力为所有 Agent 操作生成 trace 与 span并自动导出到 Google Cloud Trace。该能力默认开启适合理解执行流程与延迟。BigQuery Agent Analytics Plugin面向 ADK 系 Agent 的可选插件将 LLM 交互、工具调用及结果等详细 Agent 事件直接写入 BigQuery支撑深度分析、LLM 评测LLM as a judge、BigQuery 会话分析conversational analytics与自定义仪表盘。从仓库结构看所有生成的 Python 项目都会通过模板注入app_utils/telemetry.py见 telemetry.py其中setup_telemetry()统一负责 OpenTelemetry 与 GenAI 遥测的初始化并针对 ADK 与 LangGraph 模板分别实现了两套代码路径模板中以{%- if cookiecutter.is_adk %}区分。二、如何选择两方案特性对比特性Cloud Trace TelemetryBigQuery Agent Analytics Plugin启用方式默认开启通过--bq-analytics标志可选开启主要用途执行流程、延迟、调试深度分析、LLM as a judge、会话分析、仪表盘数据目的地Google Cloud TraceGoogle BigQuery数据模型OpenTelemetry Spans预定义的 BigQuery 表结构内容日志Span 属性元数据详细 JSON 负载大型内容可 GCS 卸载Agent 兼容性所有模板仅 ADK 系 Agent配置成本无需配置项目创建时启用标志即可官方推荐对所有 Agent 的实时调试与性能监控使用Cloud Trace Telemetry需要对 Agent 行为做详细分析、运行基于 LLM 的评测、使用 BigQuery 会话分析、追踪长期事件趋势或构建自定义报表仪表盘时仅限 ADK 系 Agent启用BigQuery Agent Analytics Plugin。三、Cloud Trace 遥测默认开启的链路可观测性所有由 Agent Starter Pack 生成的 Agent 模板都会自动接入 OpenTelemetry提供两个层面的观测能力。3.1 Agent Telemetry Events默认开启所有模板自动将 OpenTelemetry trace 与 span 导出到Cloud Trace用于分布式追踪、请求流分析与延迟分析。核心特性默认启用本地开发make playground与所有 Terraform 部署环境dev、staging、prod中均默认开启分布式追踪追踪请求在 Agent 各组件间的流转包括 LLM 调用与工具执行延迟分析通过分析单个 span 的耗时定位性能瓶颈错误可视化trace 捕获错误信息帮助定位失败环节零配置开箱即用。在 Google Cloud Console 中通过Trace Trace explorer查看 trace。3.2 Prompt-Response Logging可配置对于ADK 系 Agenttelemetry 配置可捕获GenAI 事件捕获记录模型交互、Token 用量与性能指标GCS 上传以 JSONL 格式自动将遥测数据上传到专属 GCS bucketBigQuery 集成通过外部表提供对遥测数据的 SQL 访问Cloud Logging专属日志桶GenAI 操作日志保留 10 年资源归因为事件打上 service namespace 与 version 标签便于过滤。该能力默认隐私保护——只记录元数据Token、模型名、耗时不记录提示词与响应内容NO_CONTENT模式。LangGraph 用户注意LangGraph 模板仅支持 Agent 遥测事件Cloud Trace。由于 SDK 对流式响应的限制Prompt-Response Logging 不可用。3.3 各环境下的默认行为环境默认状态配置方式本地开发make playground❌关闭未设置LOGS_BUCKET_NAME参见下文“本地启用”DevTerraform 部署✅开启Terraform 设置LOGS_BUCKET_NAME与OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTNO_CONTENTStagingTerraform 部署✅开启同上ProductionTerraform 部署✅开启同上要点所有 Terraform 部署环境dev、staging、prod自动开启遥测本地make playground默认关闭所有环境使用隐私保护的NO_CONTENT模式仅采集元数据Agent Engine 部署时平台要求显式开启 telemetry但应用运行时仍会覆盖为NO_CONTENT以保护隐私。从源码看这一行为由 telemetry.py 中的逻辑保证当LOGS_BUCKET_NAME存在且OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT ! false时代码会强制将捕获模式设为NO_CONTENT并设置OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMATjsonl、OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOKupload、OTEL_SEMCONV_STABILITY_OPT_INgen_ai_latest_experimental同时通过OTEL_RESOURCE_ATTRIBUTES写入service.namespace与service.version版本来自COMMIT_SHA默认dev。上传路径由GENAI_TELEMETRY_PATH控制默认为completions最终拼接为gs://{bucket}/{path}。3.4 开发环境验证 Prompt-Response Logging部署到开发环境后按以下步骤验证1. 部署并产生测试流量gcloud config set project YOUR_DEV_PROJECT_ID make deploy # 向 Agent 端点Cloud Run URL 或 Agent Engine发送若干测试请求2. 验证 GCS 上传PROJECT_IDyour-dev-project-id PROJECT_NAMEyour-project-name # 列出 GCS 中的遥测文件 gsutil ls gs://${PROJECT_ID}-${PROJECT_NAME}-logs/completions/ # 查看一个示例遥测文件 gsutil cat gs://${PROJECT_ID}-${PROJECT_NAME}-logs/completions/$(gsutil ls gs://${PROJECT_ID}-${PROJECT_NAME}-logs/completions/ | head -1)3. 验证 Cloud Logging 专属日志桶gcloud logging buckets describe ${PROJECT_NAME}-genai-telemetry \ --locationus-east1 \ --project${PROJECT_ID}4. 在 BigQuery 中查询遥测数据# 查询最近的 completions bq query --use_legacy_sqlfalse \ SELECT * FROM \${PROJECT_ID}.${PROJECT_NAME}_telemetry.completions\ LIMIT 10 # 查询 Cloud Logging 中的 GenAI 操作日志 bq query --use_legacy_sqlfalse \ SELECT timestamp, jsonPayload FROM \${PROJECT_ID}.${PROJECT_NAME}_genai_telemetry_logs._AllLogs\ LIMIT 103.5 常见排障若 Prompt-Response Logging 数据未出现检查 bucket 权限确保服务账号对日志 bucket 拥有storage.objectCreator角色核对环境变量确认部署中已设置LOGS_BUCKET_NAME查看应用日志在 Cloud Logging 中查找 telemetry 初始化告警确认 BigQuery 表存在执行bq ls ${PROJECT_NAME}_telemetry列出表。值得一提的是telemetry.py 对权限错误做了优雅降级——若 bucket 创建或写入失败应用不会被阻塞而是记录 warning 后继续运行这保证了可观测性故障不会拖垮线上服务。3.6 存储架构与查询视图遥测数据存储在既有日志桶中Bucket{project_id}-{project_name}-logs路径gs://{bucket}/genai-telemetry/格式换行分隔 JSONJSONL便于高效查询BigQuery 侧通过 Terraform 配置deployment/terraform/bigquery_external.tf暴露三种查询入口遥测视图{project_name}_telemetry.genai_telemetry扁平化视图预提取 JSON 字段便于查询基于直接读取 GCS 的外部表构建无数据复制、实时查询预提取字段包括service_namespace、model、input_tokens、output_tokens等原始外部表{project_name}_telemetry.genai_telemetry_raw直接访问原始 JSONL 数据适合自定义查询与结构探索反馈数据可从 Cloud Logging 的_AllLogs查询过滤条件为jsonPayload.log_typefeedback。3.7 常用 SQL 查询示例最近一小时遥测事件SELECT timestamp, service_namespace, service_version, model, operation_name, input_tokens, output_tokens FROM {project_id}.{project_name}_telemetry.genai_telemetry WHERE timestamp TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR) ORDER BY timestamp DESC LIMIT 100;按模型分析 Token 用量SELECT model, service_namespace, COUNT(*) as request_count, SUM(input_tokens) as total_input_tokens, SUM(output_tokens) as total_output_tokens, AVG(input_tokens) as avg_input_tokens, AVG(output_tokens) as avg_output_tokens FROM {project_id}.{project_name}_telemetry.genai_telemetry WHERE timestamp TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 24 HOUR) AND input_tokens IS NOT NULL GROUP BY model, service_namespace ORDER BY total_input_tokens DESC;按版本追踪请求量SELECT service_version, DATE(timestamp) as date, COUNT(*) as request_count, SUM(input_tokens output_tokens) as total_tokens FROM {project_id}.{project_name}_telemetry.genai_telemetry WHERE timestamp TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY) GROUP BY service_version, date ORDER BY date DESC, service_version;3.8 环境变量参考以下变量仅控制Prompt-Response LoggingADK 系 AgentAgent 遥测事件始终开启无需配置。变量取值用途LOGS_BUCKET_NAMEGCS bucket 路径如gs://project-logsPrompt-Response Logging 必需。未设置则日志关闭。Terraform 自动设置OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTfalse、NO_CONTENT、true控制日志开关与内容捕获false关闭NO_CONTENT开启且仅元数据默认true开启且含完整内容不推荐GENAI_TELEMETRY_PATHbucket 内路径默认completions可选覆盖 Prompt-Response 日志的上传路径3.9 本地启用与部署环境关闭本地启用 Prompt-Response Logging仅 ADK默认make playground因无 bucket 配置而关闭日志方式一手动设置环境变量export LOGS_BUCKET_NAMEgs://your-dev-project-id-your-project-name-logs export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTNO_CONTENT make playground方式二用 Terraform 部署 dev 基础设施自动创建日志桶并配置全部资源cd deployment/terraform terraform init terraform apply -var-filevars/dev.tfvars随后执行make deploy部署到 dev 项目即可带遥测运行。注意 Prompt-Response Logging 需要① ADK 系 Agent 模板LangGraph 不可用② 有效的 GCS bucketLOGS_BUCKET_NAME③ 服务账号具备 bucket 写权限④OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT设为NO_CONTENT或true。部署环境关闭 Prompt-Response LoggingCloud Run 部署编辑deployment/terraform/[dev/]service.tf将环境变量改为falseenv { name OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT value false # 原为 NO_CONTENT }然后cd deployment/terraform terraform apply -var-filevars/[dev/staging/prod].tfvars。也可通过 gcloud 临时修改下次 Terraform apply 会还原gcloud run services update YOUR_SERVICE_NAME \ --update-env-vars OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTfalse \ --regionYOUR_REGION \ --projectYOUR_PROJECT_IDAgent Engine 部署修改app_utils/deploy.py中遥测环境变量env_vars[OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT] false然后重新make deploy。四、BigQuery Agent Analytics Plugin结构化深度分析4.1 概述与适用场景BigQuery Agent Analytics Plugin 将详细的 Agent 事件直接写入 BigQuery支持基于 SQL 的长期行为、交互与性能分析。启用后该插件会取代旧的 GCS/Cloud Logging 方案的 prompt-response 日志。该功能为可选opt-in仅支持ADK 系 Agent。在以下场景应启用该插件使用 BigQuery 的高级 LLM 能力做 Agent 语义分析例如对话语义分组、会话排序、错误识别、以 LLM 为评判LLM as a judge可借助AI.Search、AI.Score、AI.Generate_text等函数使用 BigQuery 的会话分析conversational analytics用另一个会话式 Agent 来分析你的 Agent免去手写复杂 SQL构建关于 Agent 性能、工具使用与 Token 消耗的自定义仪表盘与报表保留结构化、可查询的 Agent 事件历史用于审计、微调或与其他业务数据关联对日志中的大型多模态内容使用 GCS 卸载offloading。与始终开启的 Cloud Trace telemetry 相比该插件以结构化表格式提供更细粒度的数据专为离线分析设计。4.2 前提条件使用ADK 系Agent 模板如adk、adk_a2a、agentic_rag生成的 Agent Starter Pack 项目google-adk版本1.21.0启用插件时自动添加一个 Google Cloud 项目并启用以下 API通常由 Terraform 处理BigQuery API、BigQuery Storage API。可选前提仅当有需要卸载到 GCS 的多模态数据时Cloud Storage API、BigQuery Connection API。4.3 启用插件在项目创建时使用--bq-analytics标志uv run agent-starter-pack create your-agent-name \ -a adk \ -d cloud_run \ --bq-analytics \ --cicd-runner google_cloud_build # ... 其他选项该标志做两件事对应 create.py 中的处理逻辑调整 Jinja 模板在app/agent.py中注入插件初始化代码并在 Terraform 中配置环境变量向项目添加google-adk[bigquery-analytics]1.21.0依赖。依赖添加由 template.py 中的add_bq_analytics_dependencies()实现内部通过uv add安装支持auto_approve跳过确认。此外CLI 还支持交互式选择bq-analytics选项并在某些 Agent 类型要求时自动启用参见 create.py 中“Auto-enable bq_analytics when agent requires it”的逻辑。4.4 代码配置插件在app/agent.py中配置。仓库模板的实际生成代码见 adk 模板 agent.py会在创建 BigQuery 客户端后自动建 datasetcreate_dataset(..., exists_okTrue)并以BQ_ANALYTICS_GCS_BUCKET、BQ_ANALYTICS_CONNECTION_ID环境变量初始化插件# 模板示例 from google.adk.plugins.bigquery_agent_analytics_plugin import ( BigQueryAgentAnalyticsPlugin, BigQueryLoggerConfig, ) # 插件配置 bq_config BigQueryLoggerConfig( enabledTrue, # 插件激活 gcs_bucket_nameos.environ.get(BQ_ANALYTICS_GCS_BUCKET), # (可选) 多模态内容卸载 connection_idos.environ.get(BQ_ANALYTICS_CONNECTION_ID), # (可选) BigQuery 访问 GCS 用 log_multi_modal_contentTrue, max_content_length500 * 1024, # 内联文本超过该阈值则卸载到 GCS table_idagent_events, # 默认表名 ) # 插件实例 bq_analytics_plugin BigQueryAgentAnalyticsPlugin( project_idos.environ.get(GOOGLE_CLOUD_PROJECT), dataset_idos.environ.get(BQ_ANALYTICS_DATASET_ID, adk_agent_analytics), # Terraform 会设置 table_idbq_config.table_id, configbq_config, locationos.environ.get(GOOGLE_CLOUD_LOCATION, US), ) # 注册到 App app App( name{{ cookiecutter.project_name }}, root_agentroot_agent, plugins[bq_analytics_plugin], )注意仓库模板中实际使用os.environ.get(GOOGLE_CLOUD_REGION, us-east1)作为 location见 agent.py与文档示例略有差异以你生成的项目为准。BigQueryLoggerConfig关键选项enabled开关插件gcs_bucket_name可选用于卸载大体积/二进制内容的 GCS bucket由 Terraform 设置的BQ_ANALYTICS_GCS_BUCKET注入仅有多模态数据需卸载时必需connection_id可选完整限定的 BigQuery Connection ID如us-east1.conn-id用于 GCS 访问由BQ_ANALYTICS_CONNECTION_ID注入仅有多模态数据需卸载时必需log_multi_modal_content是否处理 content parts 并卸载到 GCSmax_content_length文本 parts 卸载到 GCS 的阈值table_id写入的 BigQuery 表名默认agent_eventsevent_allowlist/event_denylist过滤要记录的事件类型batch_size写入 BigQuery 前批量缓存的行数。4.5 基础设施Terraform通过make setup-dev-env以 Terraform 部署时Dataset创建名为{project_name}_telemetry的 BigQuery datasetBQ_ANALYTICS_DATASET_ID环境变量被设置为该 IDGCS Bucket可选创建名为{project_id}-{project_name}-logs的 bucket 用于 GCS 卸载BQ_ANALYTICS_GCS_BUCKET被设置为该名称BigQuery Connection可选创建名为{project_name}-genai-telemetry的 connection让 BigQuery 能读取 GCS bucketBQ_ANALYTICS_CONNECTION_ID被设置为其完整限定 IDTableagent_events表由插件在 telemetry dataset 中首次事件时自动创建。这些环境变量在部署时由 Terraform 注入运行环境见 cloud_run service.tfBQ_ANALYTICS_DATASET_ID引用google_bigquery_dataset.telemetry_dataset的dataset_idBQ_ANALYTICS_GCS_BUCKET引用logs_data_bucket而BQ_ANALYTICS_CONNECTION_ID按${var.region}.${google_bigquery_connection.genai_telemetry_connection.connection_id}格式拼接即区域.连接ID。同一服务还始终注入LOGS_BUCKET_NAME与OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTNO_CONTENT表明两套观测链路在部署环境中可并存。4.6 Schema 参考agent_events表的 schema 由 Agent Development KitADK维护。为确保获得最新信息并保持单一事实来源请参阅 ADK 官方文档获取官方 schema 参考或在 Google Cloud Console 中直接使用 BigQuery schema 查看器查看。4.7 示例查询以下查询将YOUR_PROJECT_ID与YOUR_AGENT_NAME替换为实际值。最近事件SELECT * FROM YOUR_PROJECT_ID.YOUR_AGENT_NAME_telemetry.agent_events ORDER BY timestamp DESC LIMIT 100;工具调用与错误SELECT timestamp, JSON_VALUE(content, $.tool) AS tool_name, JSON_VALUE(content, $.args) AS tool_args, status, error_message FROM YOUR_PROJECT_ID.YOUR_AGENT_NAME_telemetry.agent_events WHERE event_type IN (TOOL_COMPLETED, TOOL_ERROR) ORDER BY timestamp DESC;LLM Token 用量SELECT agent, JSON_VALUE(attributes, $.model) AS model, SUM(CAST(JSON_VALUE(attributes, $.usage_metadata.prompt) AS INT64)) AS total_prompt_tokens, SUM(CAST(JSON_VALUE(attributes, $.usage_metadata.completion) AS INT64)) AS total_completion_tokens FROM YOUR_PROJECT_ID.YOUR_AGENT_NAME_telemetry.agent_events WHERE event_type LLM_RESPONSE AND JSON_VALUE(attributes, $.usage_metadata.prompt) IS NOT NULL GROUP BY agent, model;五、方案落地建议结合官方文档与仓库实现可归纳出以下落地路径日常监控首选 Cloud Trace零配置、全模板覆盖配合 telemetry.py 注入的资源标签namespace/version可在 Trace explorer 中快速定位服务与版本深度分析启用 BigQuery 插件在uv run agent-starter-pack create时传入--bq-analytics让模板自动注入插件代码、依赖与 Terraform 基础设施随后即可在 BigQuery 中执行本文提供的 SQL隐私默认保护两套方案默认均为元数据级别NO_CONTENT模式仅在你显式修改环境变量时才记录完整 prompt/response。六、免责声明模板化 Agent 的设计目的是在你的 Google Cloud 项目中启用你自己的用例可观测性。Google Cloud 不会记录、监控或以其他方式访问部署资源产生的任何数据。详见 Google Cloud Service Terms。通过上述两套方案你可以在数分钟内为 Agent 建立从实时链路追踪到离线深度分析的全方位观测体系同时借助 BigQuery 的 LLM 能力进一步解锁 Agent 评估与智能分析场景。【免费下载链接】agent-starter-packShip AI Agents to Google Cloud in minutes, not months. Production-ready templates with built-in CI/CD, evaluation, and observability.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-starter-pack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Agent Starter Pack 可观测性完全指南：Cloud Trace 遥测与 BigQuery Agent Analytics 双方案实战
Agent Starter Pack 可观测性完全指南Cloud Trace 遥测与 BigQuery Agent Analytics 双方案实战【免费下载链接】agent-starter-packShip AI Agents to Google Cloud in minutes, not months. Production-ready templates with built-in CI/CD, evaluation, and observability.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-starter-packAgent Starter Pack 为所有生成的 Agent 项目内置了开箱即用的监控与可观测性能力覆盖执行链路追踪、LLM 交互日志、工具调用分析与成本优化四大场景。本文以官方文档《Monitoring and Observability》为核心系统讲解默认启用的 Cloud Trace 遥测与可选开启的 BigQuery Agent Analytics Plugin 两大方案并结合仓库源码说明其底层实现原理帮助你在本地开发与 Terraform 部署环境中快速落地、验证与排障。一、两大可观测性能力总览Agent Starter Pack 提供两套互补的可观测性方案见 docs/guide/observability/index.mdAgent Telemetry EventsCloud Trace基于 OpenTelemetry 的分布式追踪能力为所有 Agent 操作生成 trace 与 span并自动导出到 Google Cloud Trace。该能力默认开启适合理解执行流程与延迟。BigQuery Agent Analytics Plugin面向 ADK 系 Agent 的可选插件将 LLM 交互、工具调用及结果等详细 Agent 事件直接写入 BigQuery支撑深度分析、LLM 评测LLM as a judge、BigQuery 会话分析conversational analytics与自定义仪表盘。从仓库结构看所有生成的 Python 项目都会通过模板注入app_utils/telemetry.py见 telemetry.py其中setup_telemetry()统一负责 OpenTelemetry 与 GenAI 遥测的初始化并针对 ADK 与 LangGraph 模板分别实现了两套代码路径模板中以{%- if cookiecutter.is_adk %}区分。二、如何选择两方案特性对比特性Cloud Trace TelemetryBigQuery Agent Analytics Plugin启用方式默认开启通过--bq-analytics标志可选开启主要用途执行流程、延迟、调试深度分析、LLM as a judge、会话分析、仪表盘数据目的地Google Cloud TraceGoogle BigQuery数据模型OpenTelemetry Spans预定义的 BigQuery 表结构内容日志Span 属性元数据详细 JSON 负载大型内容可 GCS 卸载Agent 兼容性所有模板仅 ADK 系 Agent配置成本无需配置项目创建时启用标志即可官方推荐对所有 Agent 的实时调试与性能监控使用Cloud Trace Telemetry需要对 Agent 行为做详细分析、运行基于 LLM 的评测、使用 BigQuery 会话分析、追踪长期事件趋势或构建自定义报表仪表盘时仅限 ADK 系 Agent启用BigQuery Agent Analytics Plugin。三、Cloud Trace 遥测默认开启的链路可观测性所有由 Agent Starter Pack 生成的 Agent 模板都会自动接入 OpenTelemetry提供两个层面的观测能力。3.1 Agent Telemetry Events默认开启所有模板自动将 OpenTelemetry trace 与 span 导出到Cloud Trace用于分布式追踪、请求流分析与延迟分析。核心特性默认启用本地开发make playground与所有 Terraform 部署环境dev、staging、prod中均默认开启分布式追踪追踪请求在 Agent 各组件间的流转包括 LLM 调用与工具执行延迟分析通过分析单个 span 的耗时定位性能瓶颈错误可视化trace 捕获错误信息帮助定位失败环节零配置开箱即用。在 Google Cloud Console 中通过Trace Trace explorer查看 trace。3.2 Prompt-Response Logging可配置对于ADK 系 Agenttelemetry 配置可捕获GenAI 事件捕获记录模型交互、Token 用量与性能指标GCS 上传以 JSONL 格式自动将遥测数据上传到专属 GCS bucketBigQuery 集成通过外部表提供对遥测数据的 SQL 访问Cloud Logging专属日志桶GenAI 操作日志保留 10 年资源归因为事件打上 service namespace 与 version 标签便于过滤。该能力默认隐私保护——只记录元数据Token、模型名、耗时不记录提示词与响应内容NO_CONTENT模式。LangGraph 用户注意LangGraph 模板仅支持 Agent 遥测事件Cloud Trace。由于 SDK 对流式响应的限制Prompt-Response Logging 不可用。3.3 各环境下的默认行为环境默认状态配置方式本地开发make playground❌关闭未设置LOGS_BUCKET_NAME参见下文“本地启用”DevTerraform 部署✅开启Terraform 设置LOGS_BUCKET_NAME与OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTNO_CONTENTStagingTerraform 部署✅开启同上ProductionTerraform 部署✅开启同上要点所有 Terraform 部署环境dev、staging、prod自动开启遥测本地make playground默认关闭所有环境使用隐私保护的NO_CONTENT模式仅采集元数据Agent Engine 部署时平台要求显式开启 telemetry但应用运行时仍会覆盖为NO_CONTENT以保护隐私。从源码看这一行为由 telemetry.py 中的逻辑保证当LOGS_BUCKET_NAME存在且OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT ! false时代码会强制将捕获模式设为NO_CONTENT并设置OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMATjsonl、OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOKupload、OTEL_SEMCONV_STABILITY_OPT_INgen_ai_latest_experimental同时通过OTEL_RESOURCE_ATTRIBUTES写入service.namespace与service.version版本来自COMMIT_SHA默认dev。上传路径由GENAI_TELEMETRY_PATH控制默认为completions最终拼接为gs://{bucket}/{path}。3.4 开发环境验证 Prompt-Response Logging部署到开发环境后按以下步骤验证1. 部署并产生测试流量gcloud config set project YOUR_DEV_PROJECT_ID make deploy # 向 Agent 端点Cloud Run URL 或 Agent Engine发送若干测试请求2. 验证 GCS 上传PROJECT_IDyour-dev-project-id PROJECT_NAMEyour-project-name # 列出 GCS 中的遥测文件 gsutil ls gs://${PROJECT_ID}-${PROJECT_NAME}-logs/completions/ # 查看一个示例遥测文件 gsutil cat gs://${PROJECT_ID}-${PROJECT_NAME}-logs/completions/$(gsutil ls gs://${PROJECT_ID}-${PROJECT_NAME}-logs/completions/ | head -1)3. 验证 Cloud Logging 专属日志桶gcloud logging buckets describe ${PROJECT_NAME}-genai-telemetry \ --locationus-east1 \ --project${PROJECT_ID}4. 在 BigQuery 中查询遥测数据# 查询最近的 completions bq query --use_legacy_sqlfalse \ SELECT * FROM \${PROJECT_ID}.${PROJECT_NAME}_telemetry.completions\ LIMIT 10 # 查询 Cloud Logging 中的 GenAI 操作日志 bq query --use_legacy_sqlfalse \ SELECT timestamp, jsonPayload FROM \${PROJECT_ID}.${PROJECT_NAME}_genai_telemetry_logs._AllLogs\ LIMIT 103.5 常见排障若 Prompt-Response Logging 数据未出现检查 bucket 权限确保服务账号对日志 bucket 拥有storage.objectCreator角色核对环境变量确认部署中已设置LOGS_BUCKET_NAME查看应用日志在 Cloud Logging 中查找 telemetry 初始化告警确认 BigQuery 表存在执行bq ls ${PROJECT_NAME}_telemetry列出表。值得一提的是telemetry.py 对权限错误做了优雅降级——若 bucket 创建或写入失败应用不会被阻塞而是记录 warning 后继续运行这保证了可观测性故障不会拖垮线上服务。3.6 存储架构与查询视图遥测数据存储在既有日志桶中Bucket{project_id}-{project_name}-logs路径gs://{bucket}/genai-telemetry/格式换行分隔 JSONJSONL便于高效查询BigQuery 侧通过 Terraform 配置deployment/terraform/bigquery_external.tf暴露三种查询入口遥测视图{project_name}_telemetry.genai_telemetry扁平化视图预提取 JSON 字段便于查询基于直接读取 GCS 的外部表构建无数据复制、实时查询预提取字段包括service_namespace、model、input_tokens、output_tokens等原始外部表{project_name}_telemetry.genai_telemetry_raw直接访问原始 JSONL 数据适合自定义查询与结构探索反馈数据可从 Cloud Logging 的_AllLogs查询过滤条件为jsonPayload.log_typefeedback。3.7 常用 SQL 查询示例最近一小时遥测事件SELECT timestamp, service_namespace, service_version, model, operation_name, input_tokens, output_tokens FROM {project_id}.{project_name}_telemetry.genai_telemetry WHERE timestamp TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR) ORDER BY timestamp DESC LIMIT 100;按模型分析 Token 用量SELECT model, service_namespace, COUNT(*) as request_count, SUM(input_tokens) as total_input_tokens, SUM(output_tokens) as total_output_tokens, AVG(input_tokens) as avg_input_tokens, AVG(output_tokens) as avg_output_tokens FROM {project_id}.{project_name}_telemetry.genai_telemetry WHERE timestamp TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 24 HOUR) AND input_tokens IS NOT NULL GROUP BY model, service_namespace ORDER BY total_input_tokens DESC;按版本追踪请求量SELECT service_version, DATE(timestamp) as date, COUNT(*) as request_count, SUM(input_tokens output_tokens) as total_tokens FROM {project_id}.{project_name}_telemetry.genai_telemetry WHERE timestamp TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY) GROUP BY service_version, date ORDER BY date DESC, service_version;3.8 环境变量参考以下变量仅控制Prompt-Response LoggingADK 系 AgentAgent 遥测事件始终开启无需配置。变量取值用途LOGS_BUCKET_NAMEGCS bucket 路径如gs://project-logsPrompt-Response Logging 必需。未设置则日志关闭。Terraform 自动设置OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTfalse、NO_CONTENT、true控制日志开关与内容捕获false关闭NO_CONTENT开启且仅元数据默认true开启且含完整内容不推荐GENAI_TELEMETRY_PATHbucket 内路径默认completions可选覆盖 Prompt-Response 日志的上传路径3.9 本地启用与部署环境关闭本地启用 Prompt-Response Logging仅 ADK默认make playground因无 bucket 配置而关闭日志方式一手动设置环境变量export LOGS_BUCKET_NAMEgs://your-dev-project-id-your-project-name-logs export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTNO_CONTENT make playground方式二用 Terraform 部署 dev 基础设施自动创建日志桶并配置全部资源cd deployment/terraform terraform init terraform apply -var-filevars/dev.tfvars随后执行make deploy部署到 dev 项目即可带遥测运行。注意 Prompt-Response Logging 需要① ADK 系 Agent 模板LangGraph 不可用② 有效的 GCS bucketLOGS_BUCKET_NAME③ 服务账号具备 bucket 写权限④OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT设为NO_CONTENT或true。部署环境关闭 Prompt-Response LoggingCloud Run 部署编辑deployment/terraform/[dev/]service.tf将环境变量改为falseenv { name OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT value false # 原为 NO_CONTENT }然后cd deployment/terraform terraform apply -var-filevars/[dev/staging/prod].tfvars。也可通过 gcloud 临时修改下次 Terraform apply 会还原gcloud run services update YOUR_SERVICE_NAME \ --update-env-vars OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTfalse \ --regionYOUR_REGION \ --projectYOUR_PROJECT_IDAgent Engine 部署修改app_utils/deploy.py中遥测环境变量env_vars[OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT] false然后重新make deploy。四、BigQuery Agent Analytics Plugin结构化深度分析4.1 概述与适用场景BigQuery Agent Analytics Plugin 将详细的 Agent 事件直接写入 BigQuery支持基于 SQL 的长期行为、交互与性能分析。启用后该插件会取代旧的 GCS/Cloud Logging 方案的 prompt-response 日志。该功能为可选opt-in仅支持ADK 系 Agent。在以下场景应启用该插件使用 BigQuery 的高级 LLM 能力做 Agent 语义分析例如对话语义分组、会话排序、错误识别、以 LLM 为评判LLM as a judge可借助AI.Search、AI.Score、AI.Generate_text等函数使用 BigQuery 的会话分析conversational analytics用另一个会话式 Agent 来分析你的 Agent免去手写复杂 SQL构建关于 Agent 性能、工具使用与 Token 消耗的自定义仪表盘与报表保留结构化、可查询的 Agent 事件历史用于审计、微调或与其他业务数据关联对日志中的大型多模态内容使用 GCS 卸载offloading。与始终开启的 Cloud Trace telemetry 相比该插件以结构化表格式提供更细粒度的数据专为离线分析设计。4.2 前提条件使用ADK 系Agent 模板如adk、adk_a2a、agentic_rag生成的 Agent Starter Pack 项目google-adk版本1.21.0启用插件时自动添加一个 Google Cloud 项目并启用以下 API通常由 Terraform 处理BigQuery API、BigQuery Storage API。可选前提仅当有需要卸载到 GCS 的多模态数据时Cloud Storage API、BigQuery Connection API。4.3 启用插件在项目创建时使用--bq-analytics标志uv run agent-starter-pack create your-agent-name \ -a adk \ -d cloud_run \ --bq-analytics \ --cicd-runner google_cloud_build # ... 其他选项该标志做两件事对应 create.py 中的处理逻辑调整 Jinja 模板在app/agent.py中注入插件初始化代码并在 Terraform 中配置环境变量向项目添加google-adk[bigquery-analytics]1.21.0依赖。依赖添加由 template.py 中的add_bq_analytics_dependencies()实现内部通过uv add安装支持auto_approve跳过确认。此外CLI 还支持交互式选择bq-analytics选项并在某些 Agent 类型要求时自动启用参见 create.py 中“Auto-enable bq_analytics when agent requires it”的逻辑。4.4 代码配置插件在app/agent.py中配置。仓库模板的实际生成代码见 adk 模板 agent.py会在创建 BigQuery 客户端后自动建 datasetcreate_dataset(..., exists_okTrue)并以BQ_ANALYTICS_GCS_BUCKET、BQ_ANALYTICS_CONNECTION_ID环境变量初始化插件# 模板示例 from google.adk.plugins.bigquery_agent_analytics_plugin import ( BigQueryAgentAnalyticsPlugin, BigQueryLoggerConfig, ) # 插件配置 bq_config BigQueryLoggerConfig( enabledTrue, # 插件激活 gcs_bucket_nameos.environ.get(BQ_ANALYTICS_GCS_BUCKET), # (可选) 多模态内容卸载 connection_idos.environ.get(BQ_ANALYTICS_CONNECTION_ID), # (可选) BigQuery 访问 GCS 用 log_multi_modal_contentTrue, max_content_length500 * 1024, # 内联文本超过该阈值则卸载到 GCS table_idagent_events, # 默认表名 ) # 插件实例 bq_analytics_plugin BigQueryAgentAnalyticsPlugin( project_idos.environ.get(GOOGLE_CLOUD_PROJECT), dataset_idos.environ.get(BQ_ANALYTICS_DATASET_ID, adk_agent_analytics), # Terraform 会设置 table_idbq_config.table_id, configbq_config, locationos.environ.get(GOOGLE_CLOUD_LOCATION, US), ) # 注册到 App app App( name{{ cookiecutter.project_name }}, root_agentroot_agent, plugins[bq_analytics_plugin], )注意仓库模板中实际使用os.environ.get(GOOGLE_CLOUD_REGION, us-east1)作为 location见 agent.py与文档示例略有差异以你生成的项目为准。BigQueryLoggerConfig关键选项enabled开关插件gcs_bucket_name可选用于卸载大体积/二进制内容的 GCS bucket由 Terraform 设置的BQ_ANALYTICS_GCS_BUCKET注入仅有多模态数据需卸载时必需connection_id可选完整限定的 BigQuery Connection ID如us-east1.conn-id用于 GCS 访问由BQ_ANALYTICS_CONNECTION_ID注入仅有多模态数据需卸载时必需log_multi_modal_content是否处理 content parts 并卸载到 GCSmax_content_length文本 parts 卸载到 GCS 的阈值table_id写入的 BigQuery 表名默认agent_eventsevent_allowlist/event_denylist过滤要记录的事件类型batch_size写入 BigQuery 前批量缓存的行数。4.5 基础设施Terraform通过make setup-dev-env以 Terraform 部署时Dataset创建名为{project_name}_telemetry的 BigQuery datasetBQ_ANALYTICS_DATASET_ID环境变量被设置为该 IDGCS Bucket可选创建名为{project_id}-{project_name}-logs的 bucket 用于 GCS 卸载BQ_ANALYTICS_GCS_BUCKET被设置为该名称BigQuery Connection可选创建名为{project_name}-genai-telemetry的 connection让 BigQuery 能读取 GCS bucketBQ_ANALYTICS_CONNECTION_ID被设置为其完整限定 IDTableagent_events表由插件在 telemetry dataset 中首次事件时自动创建。这些环境变量在部署时由 Terraform 注入运行环境见 cloud_run service.tfBQ_ANALYTICS_DATASET_ID引用google_bigquery_dataset.telemetry_dataset的dataset_idBQ_ANALYTICS_GCS_BUCKET引用logs_data_bucket而BQ_ANALYTICS_CONNECTION_ID按${var.region}.${google_bigquery_connection.genai_telemetry_connection.connection_id}格式拼接即区域.连接ID。同一服务还始终注入LOGS_BUCKET_NAME与OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTNO_CONTENT表明两套观测链路在部署环境中可并存。4.6 Schema 参考agent_events表的 schema 由 Agent Development KitADK维护。为确保获得最新信息并保持单一事实来源请参阅 ADK 官方文档获取官方 schema 参考或在 Google Cloud Console 中直接使用 BigQuery schema 查看器查看。4.7 示例查询以下查询将YOUR_PROJECT_ID与YOUR_AGENT_NAME替换为实际值。最近事件SELECT * FROM YOUR_PROJECT_ID.YOUR_AGENT_NAME_telemetry.agent_events ORDER BY timestamp DESC LIMIT 100;工具调用与错误SELECT timestamp, JSON_VALUE(content, $.tool) AS tool_name, JSON_VALUE(content, $.args) AS tool_args, status, error_message FROM YOUR_PROJECT_ID.YOUR_AGENT_NAME_telemetry.agent_events WHERE event_type IN (TOOL_COMPLETED, TOOL_ERROR) ORDER BY timestamp DESC;LLM Token 用量SELECT agent, JSON_VALUE(attributes, $.model) AS model, SUM(CAST(JSON_VALUE(attributes, $.usage_metadata.prompt) AS INT64)) AS total_prompt_tokens, SUM(CAST(JSON_VALUE(attributes, $.usage_metadata.completion) AS INT64)) AS total_completion_tokens FROM YOUR_PROJECT_ID.YOUR_AGENT_NAME_telemetry.agent_events WHERE event_type LLM_RESPONSE AND JSON_VALUE(attributes, $.usage_metadata.prompt) IS NOT NULL GROUP BY agent, model;五、方案落地建议结合官方文档与仓库实现可归纳出以下落地路径日常监控首选 Cloud Trace零配置、全模板覆盖配合 telemetry.py 注入的资源标签namespace/version可在 Trace explorer 中快速定位服务与版本深度分析启用 BigQuery 插件在uv run agent-starter-pack create时传入--bq-analytics让模板自动注入插件代码、依赖与 Terraform 基础设施随后即可在 BigQuery 中执行本文提供的 SQL隐私默认保护两套方案默认均为元数据级别NO_CONTENT模式仅在你显式修改环境变量时才记录完整 prompt/response。六、免责声明模板化 Agent 的设计目的是在你的 Google Cloud 项目中启用你自己的用例可观测性。Google Cloud 不会记录、监控或以其他方式访问部署资源产生的任何数据。详见 Google Cloud Service Terms。通过上述两套方案你可以在数分钟内为 Agent 建立从实时链路追踪到离线深度分析的全方位观测体系同时借助 BigQuery 的 LLM 能力进一步解锁 Agent 评估与智能分析场景。【免费下载链接】agent-starter-packShip AI Agents to Google Cloud in minutes, not months. Production-ready templates with built-in CI/CD, evaluation, and observability.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-starter-pack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考