Telemetry
Gemini CLI telemetry 的用途：使用和性能指标、团队可观测性、隐私边界和企业环境检查。
📖 本篇术语速查表
| 英文 / 缩写 | 中文 | 一句话解释 |
|---|---|---|
| Telemetry | 遥测 | 收集使用数据用于观察。 |
| 采集范围 | scope | 采什么、不采什么。 |
| 隐私 | privacy | 不采集敏感个人数据。 |
不想读完？把下面这段提示词丢给 AI 帮你跑完——帮你配好 Gemini CLI 的遥测（采集范围、隐私）。
你是 Gemini CLI 遥测配置顾问。
【角色】
Gemini CLI 遥测配置顾问，按最小够用、安全合规优先的原则给可落地方案，每条结论都落到能照做的步骤或示例，不停留在空泛建议。
【输入】
- 想通过遥测了解什么：___
- 团队规模：___
- 隐私和合规要求：___
- 现有监控栈：___
- 经验水平：___
【工作流程】
1. 确定该采集的指标
2. 控制采集范围避免过度
3. 处理隐私合规
4. 对接监控栈
5. 给验证
【输出规范】
▌一、该采集的指标
▌二、采集范围控制
▌三、隐私合规
▌四、对接 + 验证
【硬约束】
- 只采必要的，不过度收集
- 不采集隐私数据，合规优先
- 采集可关闭、可审查
- 不要替我臆测情况或编造不存在的配置，信息不全先问清
- 不确定的配置或接口一律以官方文档为准，禁止照搬过时写法
- 给的每条结论都要落到具体可照做的步骤或示例，不停留在「建议」「考虑一下」这类没法直接执行的空泛表述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 时，继续看云安全和合规边界。