Telemetry
Gemini CLI telemetry 的用途：使用和性能指标、团队可观测性、隐私边界和企业环境检查。
Telemetry 用于了解 Gemini CLI 的使用和性能。个人用户要知道它记录什么；企业用户要确认它是否符合内部合规要求。
logPrompts 是高风险开关。prompt 可能包含源码、路径、客户信息、账号线索或内部系统名，公开演示和客户项目默认不要开启。
Gemini CLI 的 telemetry 基于 OpenTelemetry，可以输出 logs、metrics 和 traces。默认 telemetry 是关闭的；是否启用、输出到哪里、是否记录 prompt，都由 .gemini/settings.json 或环境变量控制。
需要确认
- 采集哪些指标。
- 是否包含项目路径或命令信息。
- 是否能关闭或统一配置。
- 团队是否需要集中观测。
- 是否符合隐私和合规要求。
常见配置项
重点看这些配置：
telemetry.enabled/GEMINI_TELEMETRY_ENABLED：是否启用。telemetry.traces/GEMINI_TELEMETRY_TRACES_ENABLED：是否启用详细 trace。telemetry.target/GEMINI_TELEMETRY_TARGET：输出到local还是gcp。telemetry.outfile/GEMINI_TELEMETRY_OUTFILE：本地输出文件。telemetry.logPrompts/GEMINI_TELEMETRY_LOG_PROMPTS：是否记录 prompt。GEMINI_CLI_SURFACE：给脚本或内部工具打标，方便区分来源。
官方 OpenTelemetry 页面还列出 otlpEndpoint 和 otlpProtocol，默认端点类似 http://localhost:4317，协议可选 grpc 或 http。接本地 collector、Jaeger 或企业 OTEL collector 时，要把 endpoint、协议和网络可达性一起验收。
本地与云端
本地调试可以输出到 .gemini/telemetry.log，适合排查工具调用、延迟和失败原因。企业场景可以导出到 Google Cloud Trace、Cloud Monitoring 和 Cloud Logging，但需要项目、认证、IAM role 和 API 都配置正确。
如果使用 Google Cloud telemetry，至少要确认 Cloud Trace Agent、Monitoring Metric Writer、Logs Writer 等权限，以及相关 Google Cloud API 是否启用。
| 输出目标 | 适合场景 | 风险 |
|---|---|---|
| local file | 本机调试、协议排错 | 本地路径和 prompt 泄露 |
| GCP logging / monitoring | 企业可观测和审计 | IAM、项目归属、保留策略 |
| disabled | 默认个人使用 | 诊断信息不足 |
隐私建议
公开演示、录屏、客户项目和企业环境，都应先确认 telemetry 设置，避免把路径、项目名或操作信息暴露出去。
特别注意 logPrompts。如果 prompt 里可能包含业务代码、客户信息、路径、密钥线索或内部系统名称，默认不应该把它写入可共享日志。
发布前检查
教程、录屏或企业自动化上线前，至少确认：
- telemetry 是否开启。
- 输出目标是 local 还是 gcp。
- 是否记录 prompt。
- 日志文件是否进入
.gitignore/.geminiignore。 - GCP 项目和 IAM 是否属于正确组织。
- 日志保留和访问权限是否符合团队要求。
这一步要在真实任务前完成。任务跑完后再发现 prompt 被写入共享日志，补救成本会高很多。
验收方式
启用 telemetry 后，先跑一条低风险 prompt，再检查目标位置是否产生 logs、metrics 或 traces。不要等到生产自动化出问题时，才发现 telemetry 根本没写进去或写到了错误项目。
同时要检查是否出现 gemini_cli.tool_call、gemini_cli.api_request、gemini_cli.api_error、token usage、tool latency 这类关键事件或指标。只有日志文件存在，不代表可观测性已经可用。
接下来去哪
Terms and privacy
继续核对不同认证方式下的数据和条款边界。
Enterprise controls
企业 telemetry 应和 controls、license、Cloud project 一起管理。
Cloud security
把日志写到 Cloud 时，继续看云安全和合规边界。