Gemini CLI 可观测性指南

遥测提供有关 Gemini CLI 性能、健康状况和使用情况的数据。通过启用它，您可以通过跟踪、指标和结构化日志来监控操作、调试问题和优化工具使用。

Gemini CLI 的遥测系统建立在 OpenTelemetry (OTEL) 标准之上，允许您将数据发送到任何兼容的后端。

目录

启用遥测

您可以通过多种方式启用遥测。配置主要通过 .gemini/settings.json 文件和环境变量进行管理，但 CLI 标志可以覆盖这些设置以用于特定会话。

优先级顺序

以下列表列出了应用遥测设置的优先级，排名越高的项目优先级越高：

  1. CLI 标志 (gemini 命令):
    • --telemetry / --no-telemetry
    • --telemetry-target <local|gcp>
    • --telemetry-otlp-endpoint <URL>
    • --telemetry-log-prompts / --no-telemetry-log-prompts
  2. 环境变量:
    • OTEL_EXPORTER_OTLP_ENDPOINT
  3. 工作区设置文件 (.gemini/settings.json)
  4. 用户设置文件 (~/.gemini/settings.json)
  5. 默认值

示例设置

可以将以下代码添加到您的工作区 (.gemini/settings.json) 或用户 (~/.gemini/settings.json) 设置中，以启用遥测并将输出发送到 Google Cloud：

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

运行 OTEL 收集器

OTEL 收集器是接收、处理和导出遥测数据的服务。CLI 使用 OTLP/gRPC 协议发送数据。

本地收集器

使用 npm run telemetry -- --target=local 命令可以自动化设置本地遥测管道的过程。

  1. 运行命令: npm run telemetry -- --target=local
  2. 查看跟踪: 在浏览器中打开 http://localhost:16686 访问 Jaeger UI。
  3. 检查日志和指标: 脚本会将收集器输出重定向到 ~/.gemini/tmp/<projectHash>/otel/collector.log。
  4. 停止服务: 在终端中按 Ctrl+C。

Google Cloud

使用 npm run telemetry -- --target=gcp 命令可以自动化设置将数据转发到您的 Google Cloud 项目的本地 OpenTelemetry 收集器。

  1. 先决条件:
    • 拥有 Google Cloud 项目 ID。
    • 导出 OTLP_GOOGLE_CLOUD_PROJECT="your-project-id" 环境变量。
    • 使用 Google Cloud 进行身份验证。
    • 确保您的帐户具有 "Cloud Trace Agent"、"Monitoring Metric Writer" 和 "Logs Writer" IAM 角色。
  2. 运行命令: npm run telemetry -- --target=gcp
  3. 查看遥测数据: 使用脚本提供的链接在 Google Cloud Console 中查看您的跟踪、指标和日志。

日志和指标参考

所有日志和指标都包含一个通用的 `sessionId` 属性。

日志

记录的事件包括：

  • gemini_cli.config: 启动时的 CLI 配置。
  • gemini_cli.user_prompt: 用户提交提示时。
  • gemini_cli.tool_call: 每个函数调用。
  • gemini_cli.api_request: 向 Gemini API 发出请求时。
  • gemini_cli.api_error: API 请求失败时。
  • gemini_cli.api_response: 从 Gemini API 收到响应时。

指标

收集的指标包括：

  • gemini_cli.session.count: 每次 CLI 启动时递增。
  • gemini_cli.tool.call.count: 统计工具调用次数。
  • gemini_cli.tool.call.latency: 测量工具调用延迟。
  • gemini_cli.api.request.count: 统计所有 API 请求。
  • gemini_cli.api.request.latency: 测量 API 请求延迟。
  • gemini_cli.token.usage: 统计使用的令牌数。
  • gemini_cli.file.operation.count: 统计文件操作次数。