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 用量等聚合指标，而不记录任何输入/输出内容。

遥测（OpenTelemetry） #

配置参数 #

本地遥测 #

Google Cloud 遥测 #

前置条件 #

启用 GCP 遥测 #

在 Google Cloud Console 查看数据 #

数据结构参考 #

公共属性 #

主要日志事件 #

主要指标 #

Traces（链路追踪） #

客户端标识（User-Agent） #

企业环境建议 #

常见问题 #