Gemini CLI 内置 OpenTelemetry 支持，将每次 Agent 交互转为日志、指标和 Trace 三类可观测数据。在 settings.json 中设置 telemetry.enabled: true 并选择 target: gcp（上报 Google Cloud）或 target: local（写入本地文件）即可启用。企业环境中务必将 logPrompts 设为 false，避免记录用户 Prompt 内容。

遥测（OpenTelemetry）

Gemini CLI 集成了 OpenTelemetry，可将每次 Agent 交互转化为可观测数据，支持：

• 导出到任意 OpenTelemetry 后端（Google Cloud、Jaeger、Prometheus、Datadog 等）
• 标准化数据格式，避免厂商锁定
• 日志（Logs）、指标（Metrics）、链路追踪（Traces）三维度覆盖

配置参数

在 settings.json 中配置（或通过环境变量覆盖）：

配置项	环境变量	说明	可选值	默认值
enabled	GEMINI_TELEMETRY_ENABLED	启用/禁用遥测	true/false	false
traces	GEMINI_TELEMETRY_TRACES_ENABLED	启用详细属性追踪（含工具输出、文件读取）	true/false	false
target	GEMINI_TELEMETRY_TARGET	遥测数据目的地	"gcp"/"local"	"local"
otlpEndpoint	GEMINI_TELEMETRY_OTLP_ENDPOINT	OTLP 收集器端点	URL	http://localhost:4317
otlpProtocol	GEMINI_TELEMETRY_OTLP_PROTOCOL	OTLP 传输协议	"grpc"/"http"	"grpc"
outfile	GEMINI_TELEMETRY_OUTFILE	本地模式的输出文件路径	文件路径	—
logPrompts	GEMINI_TELEMETRY_LOG_PROMPTS	是否在日志中包含用户 Prompt 内容	true/false	true
useCollector	GEMINI_TELEMETRY_USE_COLLECTOR	使用外部 OTLP Collector（高级用法）	true/false	false
useCliAuth	GEMINI_TELEMETRY_USE_CLI_AUTH	使用 CLI 登录凭据进行 GCP 遥测认证（仅 gcp 模式）	true/false	false

布尔型环境变量设为 true 或 1 表示启用，其他值禁用。

---

本地遥测

适合开发调试：将遥测数据写入本地文件，无需 GCP 账号。

{
  "telemetry": {
    "enabled": true,
    "target": "local",
    "outfile": ".gemini/telemetry.log"
  }
}

写入文件后，用文本编辑器或 jq 查看：

cat .gemini/telemetry.log | jq '.body'

---

Google Cloud 遥测

将数据发送到 Google Cloud Trace（链路追踪）、Cloud Monitoring（指标）和 Cloud Logging（日志）。

前置条件

1. 设置 Google Cloud 项目 ID

# 将遥测发到专用项目（推荐）
export OTLP_GOOGLE_CLOUD_PROJECT="your-telemetry-project-id"

# 或发到与推理相同的项目
export GOOGLE_CLOUD_PROJECT="your-project-id"

2. 认证 Google Cloud

• 方式 A：Application Default Credentials（ADC），适用于服务账号或 gcloud 认证：

  # 用户账号
  gcloud auth application-default login
  
  # 服务账号
  export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

• 方式 B：CLI 凭据，最简单，使用登录 Gemini CLI 时的 OAuth 凭据：

  {
    "telemetry": {
      "enabled": true,
      "target": "gcp",
      "useCliAuth": true
    }
  }

  注意：useCliAuth 要求直接导出模式（useCollector 必须为 false），两者同时启用时遥测会被禁用。

3. 确认 IAM 权限

服务账号或用户账号需要以下角色：

• Cloud Trace Agent
• Monitoring Metric Writer
• Logs Writer

4. 启用 GCP API

gcloud services enable \
  cloudtrace.googleapis.com \
  monitoring.googleapis.com \
  logging.googleapis.com \
  --project="$OTLP_GOOGLE_CLOUD_PROJECT"

启用 GCP 遥测

{
  "telemetry": {
    "enabled": true,
    "target": "gcp"
  }
}

在 Google Cloud Console 查看数据

• 日志：Logs Explorer
• 指标：Metrics Explorer
• 链路追踪：Trace Explorer

Google Cloud Monitoring 中有预置 Gemini CLI 监控面板模板（"Gemini CLI Monitoring"），可直接使用。

---

数据结构参考

公共属性

所有遥测数据携带：

• session.id：当前会话 ID
• installation.id：安装 ID
• active_approval_mode：当前批准模式
• user.email：已认证时的用户邮箱

主要日志事件

事件名	触发时机	关键属性
gemini_cli.config	CLI 启动时	model、sandbox_enabled、mcp_servers、auth_type
gemini_cli.user_prompt	提交 Prompt 时	prompt_length、prompt（logPrompts: true 时）
gemini_cli.tool_call	每次工具调用	function_name、decision（accept/reject/auto_accept）、duration_ms、success
gemini_cli.api_request	向 Gemini API 发起请求时	model、role
gemini_cli.api_response	收到 API 响应时	model、duration_ms、input/output_token_count、status_code
gemini_cli.api_error	API 请求失败时	error.message、status_code
gemini_cli.file_operation	文件创建/读取/更新时	operation、lines、extension
gemini_cli.chat_compression	对话历史压缩时	tokens_before、tokens_after
gemini_cli.conversation_finished	会话结束时	approvalMode、turnCount
gemini_cli.agent.start / .finish	子代理启动/完成时	agent_name、duration_ms、terminate_reason
gemini_cli.hook_call	Hook 执行时	hook_name、hook_type、duration_ms、success
approval_mode_switch	切换批准模式时	from_mode、to_mode

主要指标

指标名	类型	说明
gemini_cli.session.count	Counter	每次 CLI 启动递增一次
gemini_cli.tool.call.count	Counter	工具调用次数（按 function_name、success、decision 分类）
gemini_cli.tool.call.latency	Histogram	工具调用延迟（ms）
gemini_cli.api.request.count	Counter	API 请求次数（按 model、status_code 分类）
gemini_cli.api.request.latency	Histogram	API 请求延迟（ms）
gemini_cli.token.usage	Counter	Token 用量（按 model、type=input/output/thought/cache 分类）
gemini_cli.file.operation.count	Counter	文件操作次数（按 operation=create/read/update 分类）
gemini_cli.lines.changed	Counter	增删代码行数（按 type=added/removed 分类）
gemini_cli.agent.run.count	Counter	子代理运行次数
gemini_cli.agent.duration	Histogram	子代理运行时长
gemini_cli.startup.duration	Histogram	启动各阶段耗时
gen_ai.client.token.usage	Counter	OpenTelemetry GenAI 标准 Token 用量
gen_ai.client.operation.duration	Histogram	OpenTelemetry GenAI 标准操作时长（秒）

Traces（链路追踪）

详细 Trace 属性（完整 Prompt 和工具输出）默认禁用，需设 telemetry.traces: true 才能捕获。

每个 Trace Span 包含标准属性：

• gen_ai.operation.name：操作类型（tool_call、llm_call、user_prompt、agent_call 等）
• gen_ai.agent.name：固定为 gemini-cli
• gen_ai.tool.name：执行的工具名称
• gen_ai.usage.input_tokens / gen_ai.usage.output_tokens：Token 用量
• gen_ai.conversation.id：CLI 会话 ID
• gen_ai.request.model / gen_ai.response.model：请求/响应的模型名

---

客户端标识（User-Agent）

不同集成环境在 API 请求中自动携带不同标识：

环境	User-Agent 前缀	Surface 标签
Gemini Code Assist（Agent 模式）	GeminiCLI-a2a-server	vscode
Zed（via ACP）	GeminiCLI-acp-zed	zed
IntelliJ IDEA（via ACP）	GeminiCLI-acp-intellijidea	jetbrains
标准终端	GeminiCLI	terminal

示例：GeminiCLI-a2a-server/0.34.0/gemini-pro (linux; x64; vscode)

自定义标识（用于内部工具或分发渠道追踪）：

export GEMINI_CLI_SURFACE="my-custom-tool"

效果：GeminiCLI/0.34.0/gemini-pro (linux; x64; my-custom-tool)

---

企业环境建议

企业部署时的关键遥测配置：

{
  "telemetry": {
    "enabled": true,
    "target": "gcp",
    "otlpEndpoint": "https://telemetry.example.com:4317",
    "logPrompts": false,
    "traces": false
  }
}

• logPrompts: false：必须，防止记录用户 Prompt 内容（可能含业务敏感数据）
• traces: false：详细 Trace 包含工具输出和文件读取内容，不必要时保持禁用
• 使用服务账号凭据（GOOGLE_APPLICATION_CREDENTIALS）而非 CLI 个人凭据

完整企业级配置示例见企业部署指南。

---

常见问题

Q: 如何确认遥测数据已正常发送到 GCP？

A: 启动 Gemini CLI 发送一次 Prompt 后，到 GCP Console 的 Logs Explorer 搜索 gemini_cli，应能看到 gemini_cli.config 和 gemini_cli.user_prompt 日志。如果没有，检查 IAM 权限和 API 是否已启用。

Q: logPrompts: true 的安全风险是什么？

A: 开启后，用户每次输入的 Prompt 内容会完整记录在日志中。如果用户输入了公司内部代码、客户数据或密钥等敏感信息，这些内容会出现在 GCP 日志里，存在数据泄露风险。企业环境强烈建议设为 false。

Q: 可以只收集指标不收集日志内容吗？

A: 设置 logPrompts: false 并保持 traces: false，即可仅收集工具调用次数、API 延迟、Token 用量等聚合指标，而不记录任何输入/输出内容。