跳转至

Gemini CLI 可观测性指南

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

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

启用遥测

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

配置优先级

以下列出了应用遥测设置的优先级顺序，列在上方的项目具有更高优先级：

  1. CLI 标志（用于 gemini 命令）：
  2. --telemetry / --no-telemetry：覆盖 telemetry.enabled
  3. --telemetry-target <local|gcp>：覆盖 telemetry.target
  4. --telemetry-otlp-endpoint <URL>：覆盖 telemetry.otlpEndpoint

  5. --telemetry-log-prompts / --no-telemetry-log-prompts：覆盖 telemetry.logPrompts

  6. 环境变量：

  7. OTEL_EXPORTER_OTLP_ENDPOINT：覆盖 telemetry.otlpEndpoint

  8. 工作区设置文件（.gemini/settings.json）： 来自该项目特定文件中 telemetry 对象的值。

  9. 用户设置文件（~/.gemini/settings.json）： 来自该全局用户文件中 telemetry 对象的值。

  10. 默认值： 当以上均未设置时应用。

  11. telemetry.enabled：false
  12. telemetry.target：local
  13. telemetry.otlpEndpoint：http://localhost:4317
  14. telemetry.logPrompts：true

对于 npm run telemetry -- --target=<gcp|local> 脚本： 此脚本的 --target 参数 仅 在该脚本执行期间临时覆盖 telemetry.target 设置（即选择启动哪个收集器）。它不会永久更改您的 settings.json 文件。脚本会首先查看 settings.json 中的 telemetry.target 作为默认值。

配置示例

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

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

运行 OTEL 收集器

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

更多关于 OTEL 导出器标准配置的信息，请参阅文档。

本地环境

使用 npm run telemetry -- --target=local 命令可以自动化设置本地遥测管道的流程，包括在您的 .gemini/settings.json 文件中配置必要的设置。底层脚本会安装 otelcol-contrib（OpenTelemetry 收集器）和 jaeger（用于查看追踪数据的 Jaeger UI）。使用方法如下：

  1. 运行命令： 在代码库根目录执行以下命令：

    npm run telemetry -- --target=local

    该脚本将执行以下操作：

    • 按需下载 Jaeger 和 OTEL
    • 启动本地 Jaeger 实例
    • 启动配置为接收 Gemini CLI 数据的 OTEL 收集器
    • 自动在工作区设置中启用遥测功能
    • 退出时自动禁用遥测

  2. 查看追踪数据： 打开浏览器访问 http://localhost:16686 进入 Jaeger UI。在此您可以查看 Gemini CLI 操作的详细追踪数据。

  3. 检查日志和指标： 脚本会将 OTEL 收集器输出（包含日志和指标）重定向到 ~/.gemini/tmp/<projectHash>/otel/collector.log。脚本会提供查看链接和本地实时监控遥测数据（追踪、指标、日志）的命令。

  4. 停止服务： 在运行脚本的终端中按下 Ctrl+C 即可停止 OTEL 收集器和 Jaeger 服务。

Google Cloud 平台

使用 npm run telemetry -- --target=gcp 命令可自动设置本地 OpenTelemetry 收集器，将数据转发至您的 Google Cloud 项目，包括在 .gemini/settings.json 文件中配置必要设置。底层脚本会安装 otelcol-contrib。使用方法如下：

  1. 先决条件：

  2. 拥有 Google Cloud 项目 ID

  3. 导出 GOOGLE_CLOUD_PROJECT 环境变量供 OTEL 收集器使用： 
    export OTLP_GOOGLE_CLOUD_PROJECT="your-project-id"
  4. 完成 Google Cloud 认证（例如运行 gcloud auth application-default login 或确保已设置 GOOGLE_APPLICATION_CREDENTIALS）

  5. 确保您的 Google Cloud 账户/服务账号具有以下 IAM 角色："Cloud Trace Agent"、"Monitoring Metric Writer" 和 "Logs Writer"

  6. 运行命令： 在仓库根目录执行命令：

npm run telemetry -- --target=gcp

脚本将执行以下操作：

  • 按需下载 otelcol-contrib 二进制文件
  • 启动配置好的 OTEL 收集器，接收 Gemini CLI 数据并导出至指定 Google Cloud 项目
  • 自动在工作区设置 (.gemini/settings.json) 中启用遥测并禁用沙盒模式
  • 提供直接链接查看 Google Cloud 控制台中的追踪、指标和日志

  • 退出时 (Ctrl+C) 会尝试恢复原始遥测和沙盒设置

  • 运行 Gemini CLI： 在另一个终端中运行 Gemini CLI 命令，这将生成收集器捕获的遥测数据

  • 在 Google Cloud 中查看遥测： 使用脚本提供的链接导航至 Google Cloud 控制台查看追踪、指标和日志

  • 检查本地收集器日志： 脚本将本地 OTEL 收集器输出重定向至 ~/.gemini/tmp/<projectHash>/otel/collector-gcp.log。脚本会提供查看链接和本地跟踪日志的命令

  • 停止服务： 在运行脚本的终端中按 Ctrl+C 停止 OTEL 收集器

日志与指标参考

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

  • 所有日志和指标中都包含一个公共属性 sessionId。

日志记录

日志是带有时间戳的特定事件记录。Gemini CLI 会记录以下事件：

  • gemini_cli.config: 该事件在 CLI 启动时发生一次，记录配置信息。

  • 属性：

    • model (字符串)
    • embedding_model (字符串)
    • sandbox_enabled (布尔值)
    • core_tools_enabled (字符串)
    • approval_mode (字符串)
    • api_key_enabled (布尔值)
    • vertex_ai_enabled (布尔值)
    • code_assist_enabled (布尔值)
    • log_prompts_enabled (布尔值)
    • file_filtering_respect_git_ignore (布尔值)
    • debug_mode (布尔值)
    • mcp_servers (字符串)

  • gemini_cli.user_prompt: 当用户提交提示时触发该事件。

  • 属性：

    • prompt_length
    • prompt (如果配置中 log_prompts_enabled 设为 false 则不记录该属性)

  • gemini_cli.tool_call: 每次函数调用时触发该事件。

  • 属性：

    • function_name
    • function_args
    • duration_ms
    • success (布尔值)
    • decision (字符串："accept"、"reject" 或 "modify"，如适用)
    • error (如适用)
    • error_type (如适用)

  • gemini_cli.api_request: 向 Gemini API 发起请求时触发该事件。

  • 属性：

    • model
    • request_text (如适用)

  • gemini_cli.api_error: 当 API 请求失败时触发该事件。

  • 属性：

    • model
    • error
    • error_type
    • status_code
    • duration_ms

  • gemini_cli.api_response: 收到 Gemini API 响应时触发该事件。

  • 属性：

    • model
    • status_code
    • duration_ms
    • error (可选)
    • input_token_count
    • output_token_count
    • cached_content_token_count
    • thoughts_token_count
    • tool_token_count
    • response_text (如适用)

指标

指标是对行为随时间变化的数值化度量。Gemini CLI 收集以下指标：

  • gemini_cli.session.count（计数器，整数）：每次 CLI 启动时递增一次。

  • gemini_cli.tool.call.count（计数器，整数）：统计工具调用次数。

  • 属性：

    • function_name
    • success（布尔值）
    • decision（字符串："accept"、"reject" 或 "modify"，如适用）

  • gemini_cli.tool.call.latency（直方图，毫秒）：测量工具调用延迟。

  • 属性：

    • function_name
    • decision（字符串："accept"、"reject" 或 "modify"，如适用）

  • gemini_cli.api.request.count（计数器，整数）：统计所有 API 请求次数。

  • 属性：

    • model
    • status_code
    • error_type（如适用）

  • gemini_cli.api.request.latency（直方图，毫秒）：测量 API 请求延迟。

  • 属性：

    • model

  • gemini_cli.token.usage（计数器，整数）：统计使用的 token 数量。

  • 属性：

    • model
    • type（字符串："input"、"output"、"thought"、"cache" 或 "tool"）

  • gemini_cli.file.operation.count（计数器，整数）：统计文件操作次数。

  • 属性：

    • operation（字符串："create"、"read"、"update"）：文件操作类型。
    • lines（整数，如适用）：文件中的行数。
    • mimetype（字符串，如适用）：文件的 MIME 类型。
    • extension（字符串，如适用）：文件的扩展名。