使用 OpenTelemetry 构建可观测性

本页介绍如何在 Gemini CLI 中启用并配置 OpenTelemetry。

使用 OpenTelemetry 构建可观测性

关键优势

🔍 使用分析：洞察团队的交互模式与功能采纳情况。
⚡ 性能监控：追踪响应时间、Token 消耗与资源利用率。
🐛 实时排错：及时定位瓶颈、失败与错误模式。
📊 流程优化：基于数据改进配置与工作流。
🏢 企业治理：集中监控、成本管理、合规审计，并与现有观测体系集成。

OpenTelemetry 集成

Gemini CLI 建立在 OpenTelemetry（厂商中立、业界标准的可观测性框架）之上，具备：

广泛兼容：可上报至任意 OpenTelemetry 后端（Google Cloud、Jaeger、Prometheus、Datadog 等）。
数据标准化：统一格式与采集方式，便于与其他工具协同。
前瞻性：可对接现有或未来的观测基础设施。
无厂商锁定：无需改动埋点即可切换后端。

配置方式

所有遥测行为可通过 .gemini/settings.json 配置，也可被环境变量或 CLI 参数覆盖。

设置项	环境变量	CLI 参数	说明	取值	默认值
`enabled`	`GEMINI_TELEMETRY_ENABLED`	`--telemetry` / `--no-telemetry`	是否开启遥测	`true`/`false`	`false`
`target`	`GEMINI_TELEMETRY_TARGET`	`—telemetry-target <local	gcp>`	遥测数据发送位置	`"gcp"/"local"`
`otlpEndpoint`	`GEMINI_TELEMETRY_OTLP_ENDPOINT`	`--telemetry-otlp-endpoint <URL>`	OTLP Collector 端点	URL	`http://localhost:4317`
`otlpProtocol`	`GEMINI_TELEMETRY_OTLP_PROTOCOL`	`—telemetry-otlp-protocol <grpc	http>`	OTLP 传输协议	`"grpc"/"http"`
`outfile`	`GEMINI_TELEMETRY_OUTFILE`	`--telemetry-outfile <path>`	输出至文件（优先于 `otlpEndpoint`）	文件路径	-
`logPrompts`	`GEMINI_TELEMETRY_LOG_PROMPTS`	`--telemetry-log-prompts` / `--no-telemetry-log-prompts`	日志是否包含 Prompt	`true`/`false`	`true`
`useCollector`	`GEMINI_TELEMETRY_USE_COLLECTOR`	-	是否使用外部 OTLP Collector（进阶）	`true`/`false`	`false`

布尔环境变量提示： 对应环境变量设为 true 或 1 时视作启用，其他值视作禁用。

更多配置项请参阅配置指南。

Google Cloud 遥测

前提条件

两种上报方式都需完成以下步骤：

设置 Google Cloud 项目 ID：

遥测与推理使用不同项目：

export OTLP_GOOGLE_CLOUD_PROJECT="your-telemetry-project-id"

遥测与推理使用同一项目：

export GOOGLE_CLOUD_PROJECT="your-project-id"

Google Cloud 认证：

使用个人账号：
```
gcloud auth application-default login
```

使用服务账号：

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

直接上报（推荐）

最简便的方式是将遥测直接上报至 Google Cloud。

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

若需自定义 OTLP Endpoint（如地区或代理要求）：

{
  "telemetry": {
    "enabled": true,
    "target": "gcp",
    "otlpEndpoint": "https://us-east1-otlp.googleapis.com:4317",
    "logPrompts": false
  }
}

经由 Collector 上报（进阶）

若你希望在本地 Collector 中处理后再转发至 Google Cloud，可在 telemetry 中设置 useCollector: true 并指向 Collector Endpoint：

{
  "telemetry": {
    "enabled": true,
    "target": "gcp",
    "useCollector": true,
    "otlpEndpoint": "http://collector:4317",
    "logPrompts": false
  }
}

Collector 配置需启用 Google Cloud Exporter：

exporters:
  googlecloud:
    project: your-telemetry-project-id
    user_agent: gemini-cli

本地遥测

文件输出（推荐）

若仅需本地分析，可将遥测写入文件（文本或 JSON），之后用 jq 等工具处理：

{
  "telemetry": {
    "enabled": true,
    "target": "local",
    "outfile": "~/.gemini/logs/telemetry.json",
    "logPrompts": false
  }
}

经由 Collector 上报（进阶）

也可以在本地搭建 OTLP Collector，再将数据转发至其他系统。

{
  "telemetry": {
    "enabled": true,
    "target": "local",
    "useCollector": true,
    "otlpEndpoint": "http://localhost:4317"
  }
}

Collector 示例配置（导出至文件）：

exporters:
  file:
    path: ./telemetry-collector.log
service:
  pipelines:
    traces:
      exporters: [file]
    logs:
      exporters: [file]

日志与指标

日志

Gemini CLI 发送的日志事件包括：

gemini_cli.telemetry.start：初始化遥测时触发。
gemini_cli.telemetry.stop：遥测关闭或 CLI 退出时触发。
gemini_cli.tool.call：调用工具时记录。
- 属性：function_name、success（布尔）、decision（可能为 accept/reject/modify）、tool_type（native 或 mcp）、error_type 等。
gemini_cli.tool.error：工具执行异常。
- 属性：function_name、error_type 与可选的 stacktrace。
gemini_cli.api.request：所有 API 请求。
- 属性：model、status_code、error_type。
gemini_cli.api.error：API 调用失败。
gemini_cli.token.usage：记录 Token 使用情况。
gemini_cli.file.operation：文件读写。
- 属性：operation（create/read/update）、lines、mimetype、extension、programming_language。
gemini_cli.chat_compression：会话压缩事件，记录 tokens_before 与 tokens_after。
gemini_cli.mcp.command：MCP 命令执行结果。
- 属性：command、success、exit_code。
gemini_cli.script.command：脚本或命令执行情况。
gemini_cli.prompt.truncate：Prompt 被截断时记录原始与截断内容。
gemini_cli.prompt.stringify_error：模型响应无法解析为 JSON。
- 属性：model。
gemini_cli.flash_fallback：切换到 Flash 模型的回退事件。
- 属性：auth_type。
gemini_cli.slash_command：执行斜杠命令。
- 属性：command、subcommand（如有）。
gemini_cli.extension_enable / extension_install / extension_uninstall：扩展启用、安装、卸载事件，附加 extension_name、extension_version、extension_source、status 等。

指标

指标用于度量随时间变化的行为数据。

自定义指标

gemini_cli.session.count（计数器，整型）：每次 CLI 启动计数一次。
gemini_cli.tool.call.count（计数器）：工具调用次数。
- 属性：function_name、success、decision、tool_type，以及模型/用户增删行数等。
gemini_cli.tool.call.latency（直方图，毫秒）：工具调用耗时。
- 属性：function_name、decision。
gemini_cli.api.request.count（计数器）：API 请求次数。
- 属性：model、status_code、error_type。
gemini_cli.api.request.latency（直方图，毫秒）：API 请求耗时。
- 该指标与下方符合 GenAI 语义约定的 gen_ai.client.operation.duration 有部分重合。
gemini_cli.token.usage（计数器）：Token 使用量。
- 属性：model、type（input/output/thought/cache/tool）。
gemini_cli.file.operation.count（计数器）：文件操作次数。
- 属性：operation、lines、mimetype、extension、programming_language。
gemini_cli.chat_compression（计数器）：会话压缩次数及相关 Token 变更。

GenAI 语义约定

下列指标遵循 OpenTelemetry GenAI 语义约定，便于跨 GenAI 应用统一观测：

gen_ai.client.token.usage（直方图，token）：每次操作的输入/输出 Token 数。
- 属性：gen_ai.operation.name、gen_ai.provider.name、gen_ai.token.type、gen_ai.request.model、gen_ai.response.model、server.address、server.port 等。
gen_ai.client.operation.duration（直方图，秒）：GenAI 操作耗时。
- 属性：同上，另含 error.type（若操作失败）。