agents-cli 可观测性实践Cloud Trace 与 Prompt-Response 日志的自动供给、环境变量与验证【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli本文讲解google-agents-cliagents-cliscaffold 项目中两层开箱即用的可观测能力始终开启的 Cloud Trace 分布式追踪以及由 Terraform 自动供给的 Prompt-Response 日志基础设施GCS BigQuery 日志 Sink。读完本文你能够理解各部署目标下遥测的接线方式、逐项掌握全部相关环境变量的取值含义并会用gsutil/bq命令验证部署后的日志链路是否真正打通。适用前提以下内容假设项目已通过/google-agents-cli-scaffold脚手架生成。可观测基础设施由 scaffold 项目内的 Terraformagents-cli infra single-project或agents-cli infra cicd供给一次裸的agents-cli deploy不会创建这些资源。一、Cloud Trace始终开启的分布式追踪Cloud Trace 在 scaffold 项目中默认开启、无需任何配置将 spans 与日志导出到 Cloud Trace 和 Cloud Logging可跟踪请求流经的 LLM 调用与工具执行并提供延迟分析与错误可见性。1.1 Exporter 在应用启动时接线各模板的 exporter 接线发生在应用启动阶段ADK 模板通过get_fast_api_app(otel_to_cloudTrue)完成。在 ADK 模板的 FastAPI 入口 中可以看到明确的分支逻辑——当deployment_target agent_runtime时otel_to_cloud由环境变量GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY决定取值为true/1才启用该变量由部署流程设置其他部署目标Cloud Run / GKE则直接置为True{%- if cookiecutter.deployment_target agent_runtime %} otel_to_cloud os.environ.get( GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY, ).lower() in (true, 1) {%- else %} otel_to_cloud True {%- endif %} ... app: FastAPI get_fast_api_app( ... otel_to_cloudotel_to_cloud, )其他模板在各自启动阶段调用自己的设置代码例如 LangChain 模板的 app/app_utils/telemetry.py。1.2 各部署形态的行为差异部署形态行为Agent Runtime由GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY门控部署时设置追踪数据同时出现在 Agent Engine 控制台中Cloud Run / GKEscaffold启动时自动接线导出到 Cloud Trace / Cloud Logging本地开发agents-cli playground即可用追踪可在 Cloud Console 中查看内容相关的环境变量是静态声明的部署环境在 Terraform 的service.tf中声明本地开发在.env中声明——没有运行时的动态setup_telemetry()调用。查看入口Cloud Console → Trace → Trace explorer每次请求一条 tracespans 覆盖 LLM 调用与工具执行。二、Prompt-Response 日志基础设施Terraform 一次供给全链路Prompt-Response 日志把完整提示词/响应导出到 GCS 与 BigQuery所需的全部资源由 deployment/terraform/single-project/telemetry.tf 及其 cicd/ 变体 自动创建。对照源码六个核心资源逐一说明2.1 BigQuery 遥测数据集resource google_bigquery_dataset telemetry_dataset { project var.project_id dataset_id replace(${var.project_name}_telemetry, -, _) location var.region description Dataset for GenAI telemetry data stored in GCS ... }dataset_id上的replace(..., -, _)就是项目名连字符转下划线命名约定的实现处BigQuery 数据集名不允许连字符详见第五节。2.2 BigQuery 连接GCS 访问凭证google_bigquery_connection.genai_telemetry_connection为外部表提供从 BigQuery 读取 GCS 数据所需的服务账号。源码里还有两个值得注意的细节一个time_sleep资源等待连接的服务账号在 IAM 中传播create_duration 10s随后把roles/storage.objectViewer授予该服务账号在日志桶上的读权限google_storage_bucket_iam_member.telemetry_connection_access。2.3 日志 SinkGenAI 推理日志直达 BigQueryresource google_logging_project_sink genai_logs_to_bq { name ${var.project_name}-genai-logs destination bigquery.googleapis.com/projects/${var.project_id}/datasets/${google_bigquery_dataset.telemetry_dataset.dataset_id} filter labels.\event.name\\gen_ai.client.inference.operation.details\ AND (labels.\gen_ai.input.messages_ref\ ~ \.*${var.project_name}.*\ OR labels.\gen_ai.output.messages_ref\ ~ \.*${var.project_name}.*\) unique_writer_identity true bigquery_options { use_partitioned_tables true } }Sink 按event.name标签匹配 GenAI 完成日志并限定只路由本项目名相关的条目unique_writer_identity true且配合google_bigquery_dataset_iam_member.genai_logs_bq_writer把roles/bigquery.dataEditor授予 sink 的 writer identity——这正是文档中IAM 绑定授予日志 sink 服务账号roles/bigquery.dataEditor的源码出处。2.4 预创建的日志导出表表名随部署目标变化Cloud Logging 按日志 idlog id为 sink 目标表命名因此表名随部署目标不同而不同部署目标预创建的导出表名Cloud Run / GKEgen_ai_client_inference_operation_detailsAgent Runtimeaiplatform_googleapis_com_reasoning_engine_stdoutGenAI 日志经 stdout 到达Terraform 中通过 cookiecutter 模板条件实现这一分支telemetry.tf第 145 行table_id {% if cookiecutter.deployment_target agent_runtime %}aiplatform_googleapis_com_reasoning_engine_stdout{% else %}gen_ai_client_inference_operation_details{% endif %}该表按timestamp做 DAY 级分区schema 引用 shared/genai_logs_schema.json与 cicd 变体共用。schema 注释说明了 Cloud Logging BQ 导出的字段规则顶层字段为 camelCaseCloud Logging LogEntry 的 protobuf schemalabels 展平为列键中的点变下划线如gen_ai.conversation.id→labels.gen_ai_conversation_id且全部字段 NULLABLE以避免可选字段trace、spanId、labels导致 sink 写入失败。Cloud Logging 之后会向该表追加写入并做 schema 演进。2.5 GCS 日志桶与 Completions 外部表GCS 日志桶以 NDJSON 存储 completions完整提示词/响应。外部表completionssource_format NEWLINE_DELIMITED_JSONsource_uris指向gs://bucket/completions/*通过上述 BigQuery 连接读取schema 匹配 ADK completions 格式——partsREPEATED RECORD含type/content/mime_type/uri/data/工具调用字段id/name/arguments/response、role、index。2.6 Completions 视图日志导出 × GCS 数据的 Joincompletions_view把 BigQuery 日志导出与 GCS 存储的提示词/响应数据连接起来视图 SQL 模板为 shared/completions.sql。从 SQL 实现看其核心逻辑为从日志导出表中提取gen_ai.input.messages_ref/gen_ai.output.messages_ref引用及 token 用量、agent 名、finish reasons将 input/output 引用反透视为每行一条消息引用并与 completions 外部表按messages_ref_uri c._FILE_NAME连接两级去重先在 tracespan 内去重每次 LLM 交互有独立 span再在会话级跨 trace 去重——因为输入文件包含完整会话历史早期消息会在后续 trace 中重复出现过滤掉作为输入上下文回显的 assistant 消息其内容已作为 output 捕获最终输出按conversation_id、时间戳排序的完整消息级明细包含工具调用的名称、参数与响应。2.7 应用服务账号的 IAM 角色部署模块的 iam.tf 通过app_sa_roles变量以for_each setproduct(keys(local.project_ids), var.app_sa_roles)的方式为应用服务账号批量绑定角色覆盖storage.objectCreator写 completions 到日志桶、roles/logging.logWriter、roles/cloudtrace.agent等遥测所需权限——这也是排查没有追踪数据时先检查 IAM 的依据。三、环境变量全表以下变量由 Terraform 在部署服务上自动设置可在部署目标的service.tf中逐一看到对应 env 块。其中OTEL_INSTRUMENTATION_GENAI_*系列的内容捕获/上传变量语义以opentelemetry-util-genai与 OpenTelemetry GenAI 语义约定为准。变量用途LOGS_BUCKET_NAME存放 completions 与日志的 GCS 桶名裸名不带gs://。启用 Prompt-Response 日志的必要条件未设置即视为关闭OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT仅控制traces/events 层的内容捕获合法取值为NO_CONTENT/EVENT_ONLY/SPAN_ONLY/SPAN_AND_EVENTtrue/false无效在实验性语义约定下被拒并回退为NO_CONTENTADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS仅 ADK 项目。将消息内容排除在 trace spans 之外Terraform 设置为falseADK 默认值是trueBQ_ANALYTICS_DATASET_ID遥测用 BigQuery 数据集ADK BigQuery Agent Analytics 插件仅当 scaffold 时带--bq-analytics才有BQ_ANALYTICS_CONNECTION_ID供 BigQuery 访问 GCS 的连接仅--bq-analytics时BQ_ANALYTICS_GCS_BUCKETBigQuery Analytics 多模态卸载所用 GCS 桶仅--bq-analytics时OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK设为upload即启用完整 completions 导出到 GCS即 Prompt-Response 日志特性本体OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATHcompletions 上传的 GCS 路径如gs://bucket/completionsOTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMATcompletions 上传格式如jsonl部署目标的 env 块在 cloud_run/python 的 single-project/service.tf 中可直接核对LOGS_BUCKET_NAME取google_storage_bucket.logs_data_bucket.name捕获模式固定为NO_CONTENT上传格式jsonl、hookupload、base pathgs://bucket/completions。两个独立的内容控制层理解配置行为的关键层捕获内容控制变量Terraform 部署默认GCS/BigQuery completions完整提示词/响应OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOKuploadLOGS_BUCKET_NAME开启完整内容Trace spans / Cloud Logging eventsspan/event 内容OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTADK 项目另加ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANSfalse关闭NO_CONTENT两层相互独立只要上传变量设置GCS/BigQuery 上传就捕获完整内容不受OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT影响——后者只管辖 traces/events 层。四、启用与关闭4.1 本地启用遥测配置完全由环境变量驱动本地只需设置与 Terraform 为部署 agent 所设置的相同变量再运行agents-cli playgroundexport LOGS_BUCKET_NAMEyour-bucket-name # 裸名不带 gs:// export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTNO_CONTENT # 或 EVENT_ONLY内容进 Cloud Logging events export OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOKupload export OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATHgs://your-bucket-name/completions export OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMATjsonl export OTEL_SEMCONV_STABILITY_OPT_INgen_ai_latest_experimental注意OTEL_SEMCONV_STABILITY_OPT_INgen_ai_latest_experimental是 GenAI completion/upload 语义约定生效的前提。4.2 部署环境关闭traces/events 中的内容默认已经是关闭状态NO_CONTENT——再次强调true/false在实验性语义约定下不是合法取值会被回退到NO_CONTENT。要彻底关闭到 GCS/BigQuery 的 Prompt-Response 日志需从部署目标对应的service.tfsingle-project/或cicd/变体中删除整个上传块OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK、OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH、LOGS_BUCKET_NAME然后重新 apply Terraform。五、BigQuery 数据集命名约定BigQuery 数据集名不能包含连字符Terraform 创建数据集时会自动把项目名中的连字符转换为下划线项目名my-agent→ BQ 数据集my_agent_telemetry只创建一个数据集{name}_telemetry其中包含指向 GCS completions 数据NDJSON的外部表预创建的日志导出表Cloud Run / GKE 为gen_ai_client_inference_operation_detailsAgent Runtime 为aiplatform_googleapis_com_reasoning_engine_stdout;completions_view。在项目中发现实际数据集名bq ls --project_id${PROJECT_ID}六、部署后验证遥测链路部署后按以下顺序验证 Prompt-Response 日志是否真正工作PROJECT_IDyour-dev-project-id PROJECT_NAMEyour-app-name # agents-cli 项目名不是 GCP 项目 ID # 1. 检查 GCS 数据 gsutil ls gs://${PROJECT_ID}-${PROJECT_NAME}-logs/completions/ # 2. 检查 BigQuery 日志导出表经 sink 到达可能有几分钟延迟。 # 表名随目标而异Cloud Run / GKE 为 gen_ai_client_inference_operation_details # Agent Runtime 为 aiplatform_googleapis_com_reasoning_engine_stdout bq query --use_legacy_sqlfalse \ SELECT COUNT(*) FROM \${PROJECT_ID}.${PROJECT_NAME//-/_}_telemetry.gen_ai_client_inference_operation_details\ # 3. 查询 completions 外部表 bq query --use_legacy_sqlfalse \ SELECT * FROM \${PROJECT_ID}.${PROJECT_NAME//-/_}_telemetry.completions\ LIMIT 10 # 4. 查询 completions 视图日志导出 × GCS 数据的 join bq query --use_legacy_sqlfalse \ SELECT * FROM \${PROJECT_ID}.${PROJECT_NAME//-/_}_telemetry.completions_view\ LIMIT 10其中${PROJECT_NAME//-/_}是 Bash 的字符串替换语法等价于命名约定中的连字符转下划线。日志桶命名模式为gs://${PROJECT_ID}-${PROJECT_NAME}-logs/completions/。数据未出现时的排查顺序确认LOGS_BUCKET_NAME已设置确认应用服务账号在日志桶上拥有storage.objectCreator角色在 Cloud Logging 中检查应用日志里的遥测设置告警日志经 sink 导出到 BigQuery 有几分钟的传播延迟稍后重试。七、延伸同一基础设施支撑用户反馈收集同一套结构化日志 → 日志 Sink → BigQuery基础设施可复用于收集终端用户反馈评分、点赞/点踩、自由文本应用侧用 Pydantic 模型定义带固定判别字段的请求体FastAPI 端点以log_struct写入结构化日志条目落入jsonPayload而非纯文本Terraform 中再加一个按log_type过滤的日志 sink 指向遥测数据集。完整实现参见 references/feedback-mechanism.md。八、参考资源文件内容references/cloud-trace-and-logging.md本文对应的 skill 参考文档Terraform 供给资源、环境变量、验证命令references/feedback-mechanism.md用户反馈端点请求模型、结构化日志、日志 sink → BigQueryreferences/bigquery-agent-analytics.mdBigQuery Agent Analytics 插件--bq-analyticsdocs/src/guide/observability/cloud-trace.md面向开发者的 Cloud Trace 验证与本地启停操作指南single-project/telemetry.tf遥测资源定义数据集、连接、sink、外部表、导出表、视图shared/completions.sqlcompletions_view 的 Join 与去重 SQLagents/adk/app/fast_api_app.pyADK 模板中otel_to_cloud的启动接线cloud_run single-project/service.tf部署目标的遥测环境变量 env 块适用前提与限制以上均假设项目由 scaffold 生成agents-cli infra single-project/infra cicd供给 Terraform 基础设施Agent Runtime 目标下建议先运行infra single-project再deploy否则 Terraform 与 SDK 部署的资源归属会冲突--bq-analytics相关环境变量仅在 scaffold 时选择该选项才存在。【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 agents-cli 可观测性实践：Cloud Trace 与 Prompt-Response 日志的自动供给、环境变量与验证
agents-cli 可观测性实践Cloud Trace 与 Prompt-Response 日志的自动供给、环境变量与验证【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli本文讲解google-agents-cliagents-cliscaffold 项目中两层开箱即用的可观测能力始终开启的 Cloud Trace 分布式追踪以及由 Terraform 自动供给的 Prompt-Response 日志基础设施GCS BigQuery 日志 Sink。读完本文你能够理解各部署目标下遥测的接线方式、逐项掌握全部相关环境变量的取值含义并会用gsutil/bq命令验证部署后的日志链路是否真正打通。适用前提以下内容假设项目已通过/google-agents-cli-scaffold脚手架生成。可观测基础设施由 scaffold 项目内的 Terraformagents-cli infra single-project或agents-cli infra cicd供给一次裸的agents-cli deploy不会创建这些资源。一、Cloud Trace始终开启的分布式追踪Cloud Trace 在 scaffold 项目中默认开启、无需任何配置将 spans 与日志导出到 Cloud Trace 和 Cloud Logging可跟踪请求流经的 LLM 调用与工具执行并提供延迟分析与错误可见性。1.1 Exporter 在应用启动时接线各模板的 exporter 接线发生在应用启动阶段ADK 模板通过get_fast_api_app(otel_to_cloudTrue)完成。在 ADK 模板的 FastAPI 入口 中可以看到明确的分支逻辑——当deployment_target agent_runtime时otel_to_cloud由环境变量GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY决定取值为true/1才启用该变量由部署流程设置其他部署目标Cloud Run / GKE则直接置为True{%- if cookiecutter.deployment_target agent_runtime %} otel_to_cloud os.environ.get( GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY, ).lower() in (true, 1) {%- else %} otel_to_cloud True {%- endif %} ... app: FastAPI get_fast_api_app( ... otel_to_cloudotel_to_cloud, )其他模板在各自启动阶段调用自己的设置代码例如 LangChain 模板的 app/app_utils/telemetry.py。1.2 各部署形态的行为差异部署形态行为Agent Runtime由GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY门控部署时设置追踪数据同时出现在 Agent Engine 控制台中Cloud Run / GKEscaffold启动时自动接线导出到 Cloud Trace / Cloud Logging本地开发agents-cli playground即可用追踪可在 Cloud Console 中查看内容相关的环境变量是静态声明的部署环境在 Terraform 的service.tf中声明本地开发在.env中声明——没有运行时的动态setup_telemetry()调用。查看入口Cloud Console → Trace → Trace explorer每次请求一条 tracespans 覆盖 LLM 调用与工具执行。二、Prompt-Response 日志基础设施Terraform 一次供给全链路Prompt-Response 日志把完整提示词/响应导出到 GCS 与 BigQuery所需的全部资源由 deployment/terraform/single-project/telemetry.tf 及其 cicd/ 变体 自动创建。对照源码六个核心资源逐一说明2.1 BigQuery 遥测数据集resource google_bigquery_dataset telemetry_dataset { project var.project_id dataset_id replace(${var.project_name}_telemetry, -, _) location var.region description Dataset for GenAI telemetry data stored in GCS ... }dataset_id上的replace(..., -, _)就是项目名连字符转下划线命名约定的实现处BigQuery 数据集名不允许连字符详见第五节。2.2 BigQuery 连接GCS 访问凭证google_bigquery_connection.genai_telemetry_connection为外部表提供从 BigQuery 读取 GCS 数据所需的服务账号。源码里还有两个值得注意的细节一个time_sleep资源等待连接的服务账号在 IAM 中传播create_duration 10s随后把roles/storage.objectViewer授予该服务账号在日志桶上的读权限google_storage_bucket_iam_member.telemetry_connection_access。2.3 日志 SinkGenAI 推理日志直达 BigQueryresource google_logging_project_sink genai_logs_to_bq { name ${var.project_name}-genai-logs destination bigquery.googleapis.com/projects/${var.project_id}/datasets/${google_bigquery_dataset.telemetry_dataset.dataset_id} filter labels.\event.name\\gen_ai.client.inference.operation.details\ AND (labels.\gen_ai.input.messages_ref\ ~ \.*${var.project_name}.*\ OR labels.\gen_ai.output.messages_ref\ ~ \.*${var.project_name}.*\) unique_writer_identity true bigquery_options { use_partitioned_tables true } }Sink 按event.name标签匹配 GenAI 完成日志并限定只路由本项目名相关的条目unique_writer_identity true且配合google_bigquery_dataset_iam_member.genai_logs_bq_writer把roles/bigquery.dataEditor授予 sink 的 writer identity——这正是文档中IAM 绑定授予日志 sink 服务账号roles/bigquery.dataEditor的源码出处。2.4 预创建的日志导出表表名随部署目标变化Cloud Logging 按日志 idlog id为 sink 目标表命名因此表名随部署目标不同而不同部署目标预创建的导出表名Cloud Run / GKEgen_ai_client_inference_operation_detailsAgent Runtimeaiplatform_googleapis_com_reasoning_engine_stdoutGenAI 日志经 stdout 到达Terraform 中通过 cookiecutter 模板条件实现这一分支telemetry.tf第 145 行table_id {% if cookiecutter.deployment_target agent_runtime %}aiplatform_googleapis_com_reasoning_engine_stdout{% else %}gen_ai_client_inference_operation_details{% endif %}该表按timestamp做 DAY 级分区schema 引用 shared/genai_logs_schema.json与 cicd 变体共用。schema 注释说明了 Cloud Logging BQ 导出的字段规则顶层字段为 camelCaseCloud Logging LogEntry 的 protobuf schemalabels 展平为列键中的点变下划线如gen_ai.conversation.id→labels.gen_ai_conversation_id且全部字段 NULLABLE以避免可选字段trace、spanId、labels导致 sink 写入失败。Cloud Logging 之后会向该表追加写入并做 schema 演进。2.5 GCS 日志桶与 Completions 外部表GCS 日志桶以 NDJSON 存储 completions完整提示词/响应。外部表completionssource_format NEWLINE_DELIMITED_JSONsource_uris指向gs://bucket/completions/*通过上述 BigQuery 连接读取schema 匹配 ADK completions 格式——partsREPEATED RECORD含type/content/mime_type/uri/data/工具调用字段id/name/arguments/response、role、index。2.6 Completions 视图日志导出 × GCS 数据的 Joincompletions_view把 BigQuery 日志导出与 GCS 存储的提示词/响应数据连接起来视图 SQL 模板为 shared/completions.sql。从 SQL 实现看其核心逻辑为从日志导出表中提取gen_ai.input.messages_ref/gen_ai.output.messages_ref引用及 token 用量、agent 名、finish reasons将 input/output 引用反透视为每行一条消息引用并与 completions 外部表按messages_ref_uri c._FILE_NAME连接两级去重先在 tracespan 内去重每次 LLM 交互有独立 span再在会话级跨 trace 去重——因为输入文件包含完整会话历史早期消息会在后续 trace 中重复出现过滤掉作为输入上下文回显的 assistant 消息其内容已作为 output 捕获最终输出按conversation_id、时间戳排序的完整消息级明细包含工具调用的名称、参数与响应。2.7 应用服务账号的 IAM 角色部署模块的 iam.tf 通过app_sa_roles变量以for_each setproduct(keys(local.project_ids), var.app_sa_roles)的方式为应用服务账号批量绑定角色覆盖storage.objectCreator写 completions 到日志桶、roles/logging.logWriter、roles/cloudtrace.agent等遥测所需权限——这也是排查没有追踪数据时先检查 IAM 的依据。三、环境变量全表以下变量由 Terraform 在部署服务上自动设置可在部署目标的service.tf中逐一看到对应 env 块。其中OTEL_INSTRUMENTATION_GENAI_*系列的内容捕获/上传变量语义以opentelemetry-util-genai与 OpenTelemetry GenAI 语义约定为准。变量用途LOGS_BUCKET_NAME存放 completions 与日志的 GCS 桶名裸名不带gs://。启用 Prompt-Response 日志的必要条件未设置即视为关闭OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT仅控制traces/events 层的内容捕获合法取值为NO_CONTENT/EVENT_ONLY/SPAN_ONLY/SPAN_AND_EVENTtrue/false无效在实验性语义约定下被拒并回退为NO_CONTENTADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS仅 ADK 项目。将消息内容排除在 trace spans 之外Terraform 设置为falseADK 默认值是trueBQ_ANALYTICS_DATASET_ID遥测用 BigQuery 数据集ADK BigQuery Agent Analytics 插件仅当 scaffold 时带--bq-analytics才有BQ_ANALYTICS_CONNECTION_ID供 BigQuery 访问 GCS 的连接仅--bq-analytics时BQ_ANALYTICS_GCS_BUCKETBigQuery Analytics 多模态卸载所用 GCS 桶仅--bq-analytics时OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK设为upload即启用完整 completions 导出到 GCS即 Prompt-Response 日志特性本体OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATHcompletions 上传的 GCS 路径如gs://bucket/completionsOTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMATcompletions 上传格式如jsonl部署目标的 env 块在 cloud_run/python 的 single-project/service.tf 中可直接核对LOGS_BUCKET_NAME取google_storage_bucket.logs_data_bucket.name捕获模式固定为NO_CONTENT上传格式jsonl、hookupload、base pathgs://bucket/completions。两个独立的内容控制层理解配置行为的关键层捕获内容控制变量Terraform 部署默认GCS/BigQuery completions完整提示词/响应OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOKuploadLOGS_BUCKET_NAME开启完整内容Trace spans / Cloud Logging eventsspan/event 内容OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTADK 项目另加ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANSfalse关闭NO_CONTENT两层相互独立只要上传变量设置GCS/BigQuery 上传就捕获完整内容不受OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT影响——后者只管辖 traces/events 层。四、启用与关闭4.1 本地启用遥测配置完全由环境变量驱动本地只需设置与 Terraform 为部署 agent 所设置的相同变量再运行agents-cli playgroundexport LOGS_BUCKET_NAMEyour-bucket-name # 裸名不带 gs:// export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTNO_CONTENT # 或 EVENT_ONLY内容进 Cloud Logging events export OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOKupload export OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATHgs://your-bucket-name/completions export OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMATjsonl export OTEL_SEMCONV_STABILITY_OPT_INgen_ai_latest_experimental注意OTEL_SEMCONV_STABILITY_OPT_INgen_ai_latest_experimental是 GenAI completion/upload 语义约定生效的前提。4.2 部署环境关闭traces/events 中的内容默认已经是关闭状态NO_CONTENT——再次强调true/false在实验性语义约定下不是合法取值会被回退到NO_CONTENT。要彻底关闭到 GCS/BigQuery 的 Prompt-Response 日志需从部署目标对应的service.tfsingle-project/或cicd/变体中删除整个上传块OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK、OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH、LOGS_BUCKET_NAME然后重新 apply Terraform。五、BigQuery 数据集命名约定BigQuery 数据集名不能包含连字符Terraform 创建数据集时会自动把项目名中的连字符转换为下划线项目名my-agent→ BQ 数据集my_agent_telemetry只创建一个数据集{name}_telemetry其中包含指向 GCS completions 数据NDJSON的外部表预创建的日志导出表Cloud Run / GKE 为gen_ai_client_inference_operation_detailsAgent Runtime 为aiplatform_googleapis_com_reasoning_engine_stdout;completions_view。在项目中发现实际数据集名bq ls --project_id${PROJECT_ID}六、部署后验证遥测链路部署后按以下顺序验证 Prompt-Response 日志是否真正工作PROJECT_IDyour-dev-project-id PROJECT_NAMEyour-app-name # agents-cli 项目名不是 GCP 项目 ID # 1. 检查 GCS 数据 gsutil ls gs://${PROJECT_ID}-${PROJECT_NAME}-logs/completions/ # 2. 检查 BigQuery 日志导出表经 sink 到达可能有几分钟延迟。 # 表名随目标而异Cloud Run / GKE 为 gen_ai_client_inference_operation_details # Agent Runtime 为 aiplatform_googleapis_com_reasoning_engine_stdout bq query --use_legacy_sqlfalse \ SELECT COUNT(*) FROM \${PROJECT_ID}.${PROJECT_NAME//-/_}_telemetry.gen_ai_client_inference_operation_details\ # 3. 查询 completions 外部表 bq query --use_legacy_sqlfalse \ SELECT * FROM \${PROJECT_ID}.${PROJECT_NAME//-/_}_telemetry.completions\ LIMIT 10 # 4. 查询 completions 视图日志导出 × GCS 数据的 join bq query --use_legacy_sqlfalse \ SELECT * FROM \${PROJECT_ID}.${PROJECT_NAME//-/_}_telemetry.completions_view\ LIMIT 10其中${PROJECT_NAME//-/_}是 Bash 的字符串替换语法等价于命名约定中的连字符转下划线。日志桶命名模式为gs://${PROJECT_ID}-${PROJECT_NAME}-logs/completions/。数据未出现时的排查顺序确认LOGS_BUCKET_NAME已设置确认应用服务账号在日志桶上拥有storage.objectCreator角色在 Cloud Logging 中检查应用日志里的遥测设置告警日志经 sink 导出到 BigQuery 有几分钟的传播延迟稍后重试。七、延伸同一基础设施支撑用户反馈收集同一套结构化日志 → 日志 Sink → BigQuery基础设施可复用于收集终端用户反馈评分、点赞/点踩、自由文本应用侧用 Pydantic 模型定义带固定判别字段的请求体FastAPI 端点以log_struct写入结构化日志条目落入jsonPayload而非纯文本Terraform 中再加一个按log_type过滤的日志 sink 指向遥测数据集。完整实现参见 references/feedback-mechanism.md。八、参考资源文件内容references/cloud-trace-and-logging.md本文对应的 skill 参考文档Terraform 供给资源、环境变量、验证命令references/feedback-mechanism.md用户反馈端点请求模型、结构化日志、日志 sink → BigQueryreferences/bigquery-agent-analytics.mdBigQuery Agent Analytics 插件--bq-analyticsdocs/src/guide/observability/cloud-trace.md面向开发者的 Cloud Trace 验证与本地启停操作指南single-project/telemetry.tf遥测资源定义数据集、连接、sink、外部表、导出表、视图shared/completions.sqlcompletions_view 的 Join 与去重 SQLagents/adk/app/fast_api_app.pyADK 模板中otel_to_cloud的启动接线cloud_run single-project/service.tf部署目标的遥测环境变量 env 块适用前提与限制以上均假设项目由 scaffold 生成agents-cli infra single-project/infra cicd供给 Terraform 基础设施Agent Runtime 目标下建议先运行infra single-project再deploy否则 Terraform 与 SDK 部署的资源归属会冲突--bq-analytics相关环境变量仅在 scaffold 时选择该选项才存在。【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考