---
title: "Telemetry"
description: "Gemini CLI telemetry 的用途：使用和性能指标、团队可观测性、隐私边界和企业环境检查。"
verifiedAt: "2026-05-09"
---

Telemetry 用于了解 Gemini CLI 的使用和性能。个人用户要知道它记录什么；企业用户要确认它是否符合内部合规要求。

> [!WARNING]
> `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 里可能包含业务代码、客户信息、路径、密钥线索或内部系统名称，默认不应该把它写入可共享日志。

## 发布前检查

教程、录屏或企业自动化上线前，至少确认：

1. telemetry 是否开启。
2. 输出目标是 local 还是 gcp。
3. 是否记录 prompt。
4. 日志文件是否进入 `.gitignore` / `.geminiignore`。
5. GCP 项目和 IAM 是否属于正确组织。
6. 日志保留和访问权限是否符合团队要求。

这一步要在真实任务前完成。任务跑完后再发现 prompt 被写入共享日志，补救成本会高很多。

## 验收方式

启用 telemetry 后，先跑一条低风险 prompt，再检查目标位置是否产生 logs、metrics 或 traces。不要等到生产自动化出问题时，才发现 telemetry 根本没写进去或写到了错误项目。

同时要检查是否出现 `gemini_cli.tool_call`、`gemini_cli.api_request`、`gemini_cli.api_error`、token usage、tool latency 这类关键事件或指标。只有日志文件存在，不代表可观测性已经可用。

## 接下来去哪

<Cards>
  <Card title="Terms and privacy" description="继续核对不同认证方式下的数据和条款边界。" href="/docs/gemini-cli/official/06-security-enterprise/65-terms-privacy" />
  <Card title="Enterprise controls" description="企业 telemetry 应和 controls、license、Cloud project 一起管理。" href="/docs/gemini-cli/official/06-security-enterprise/63-enterprise-controls" />
  <Card title="Cloud security" description="把日志写到 Cloud 时，继续看云安全和合规边界。" href="/docs/gemini-cli/official/06-security-enterprise/66-cloud-security-privacy" />
</Cards>

## 官方来源

- [Gemini CLI telemetry](https://github.com/google-gemini/gemini-cli/blob/main/docs/telemetry.md)
- [Gemini CLI enterprise](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/enterprise.md)
