使用 OpenTelemetry 进行可观测性

了解如何为 Gemini CLI 启用和设置 OpenTelemetry。

主要优势

🔍 使用分析：了解团队中的交互模式和功能采用情况
⚡ 性能监控：跟踪响应时间、token 消耗和资源利用率
🐛 实时调试：在问题发生时识别瓶颈、故障和错误模式
📊 工作流优化：做出明智的决策以改进配置和流程
🏢 企业治理：监控跨团队的使用情况、跟踪成本、确保合规性，并与现有监控基础设施集成

OpenTelemetry 集成

基于 OpenTelemetry — 供应商中立的行业标准可观测性框架 — Gemini CLI 的可观测性系统提供：

通用兼容性：导出到任何 OpenTelemetry 后端（Google Cloud、Jaeger、Prometheus、Datadog 等）
标准化数据：在你的工具链中使用一致的格式和收集方法
面向未来的集成：与现有和未来的可观测性基础设施连接
无供应商锁定：在后端之间切换而无需更改你的检测

配置

所有遥测行为都通过你的 .gemini/settings.json 文件控制。环境变量可用于覆盖文件中的设置。

设置	环境变量	描述	值	默认值
`enabled`	`GEMINI_TELEMETRY_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`	将遥测保存到文件（覆盖 `otlpEndpoint`）	文件路径	-
`logPrompts`	`GEMINI_TELEMETRY_LOG_PROMPTS`	在遥测日志中包含提示	`true`/`false`	`true`
`useCollector`	`GEMINI_TELEMETRY_USE_COLLECTOR`	使用外部 OTLP 收集器（高级）	`true`/`false`	`false`
`useCliAuth`	`GEMINI_TELEMETRY_USE_CLI_AUTH`	使用 CLI 凭据进行遥测（仅限 GCP 目标）	`true`/`false`	`false`

有关所有配置选项的详细信息，请参阅配置指南。

Google Cloud 遥测

前提条件

在使用以下任一方法之前，请完成以下步骤：

设置你的 Google Cloud 项目 ID：
- 对于与推理分开的项目中的遥测：
  bash
```
export OTLP_GOOGLE_CLOUD_PROJECT="your-telemetry-project-id"
```
- 对于与推理相同项目中的遥测：
  bash
```
export GOOGLE_CLOUD_PROJECT="your-project-id"
```

使用 Google Cloud 进行身份验证：

如果使用用户账户：
bash
```
gcloud auth application-default login
```

如果使用服务账户：

bash

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

确保你的账户或服务账户具有以下 IAM 角色：
- Cloud Trace Agent
- Monitoring Metric Writer
- Logs Writer

启用所需的 Google Cloud API（如果尚未启用）：

bash

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

直接导出（推荐）

直接将遥测发送到 Google Cloud 服务。无需收集器。

在你的 .gemini/settings.json 中启用遥测：

json

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

运行 Gemini CLI 并发送提示。
查看日志和指标：
- 发送提示后在浏览器中打开 Google Cloud Console：
  - 日志：https://console.cloud.google.com/logs/
  - 指标：https://console.cloud.google.com/monitoring/metrics-explorer
  - 跟踪：https://console.cloud.google.com/traces/list

本地遥测

对于本地开发和调试，你可以在本地捕获遥测数据：

基于文件的输出（推荐）

在你的 .gemini/settings.json 中启用遥测：

json

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

运行 Gemini CLI 并发送提示。
在指定文件中查看日志和指标（例如 .gemini/telemetry.log）。

基于收集器的导出（高级）

运行自动化脚本：
bash
```
npm run telemetry -- --target=local
```
这将：
- 下载并启动 Jaeger 和 OTEL 收集器
- 为本地遥测配置你的工作区
- 在 http://localhost:16686 提供 Jaeger UI
- 将日志/指标保存到 ~/.gemini/tmp/<projectHash>/otel/collector.log
- 退出时停止收集器（例如 Ctrl+C）
运行 Gemini CLI 并发送提示。
在 http://localhost:16686 查看跟踪，在收集器日志文件中查看日志/指标。

日志和指标

以下部分描述了为 Gemini CLI 生成的日志和指标的结构。

session.id、installation.id 和 user.email（仅在使用 Google 账户进行身份验证时可用）作为所有日志和指标的公共属性包含在内。

日志

日志是特定事件的带时间戳记录。以下事件按类别分组记录 Gemini CLI。

会话

捕获启动配置和用户提示提交。

gemini_cli.config：在启动时发出一次，包含 CLI 配置。
gemini_cli.user_prompt：当用户提交提示时发出。

工具

捕获工具执行、输出截断和 Smart Edit 行为。

gemini_cli.tool_call：为每个工具（函数）调用发出。
gemini_cli.tool_output_truncated：工具调用的输出被截断。
gemini_cli.smart_edit_strategy：选择的 Smart Edit 策略。
gemini_cli.smart_edit_correction：Smart Edit 校正结果。

文件

跟踪工具执行的文件操作。

gemini_cli.file_operation：为每个文件操作发出。

API

捕获 Gemini API 请求、响应和错误。

gemini_cli.api_request：发送到 Gemini API 的请求。
gemini_cli.api_response：从 Gemini API 收到的响应。
gemini_cli.api_error：API 请求失败。

指标

指标是随时间变化的行为的数值测量。

会话

在启动时计数 CLI 会话。

gemini_cli.session.count（Counter，Int）：每次 CLI 启动时递增一次。

工具

测量工具使用和延迟。

gemini_cli.tool.call.count（Counter，Int）：计数工具调用。
gemini_cli.tool.call.latency（Histogram，ms）：测量工具调用延迟。

API

跟踪 API 请求量和延迟。

gemini_cli.api.request.count（Counter，Int）：计数所有 API 请求。
gemini_cli.api.request.latency（Histogram，ms）：测量 API 请求延迟。

Token 使用

按模型和类型跟踪使用的 token。

gemini_cli.token.usage（Counter，Int）：计数使用的 token。

文件

计数带有基本上下文的文件操作。

gemini_cli.file.operation.count（Counter，Int）：计数文件操作。
gemini_cli.lines.changed（Counter，Int）：更改的行数（来自文件差异）。

使用 OpenTelemetry 进行可观测性 ​

主要优势 ​

OpenTelemetry 集成 ​

配置 ​

Google Cloud 遥测 ​

前提条件 ​

直接导出（推荐） ​

本地遥测 ​

基于文件的输出（推荐） ​

基于收集器的导出（高级） ​

日志和指标 ​

日志 ​

会话 ​

工具 ​

文件 ​

API ​

指标 ​