Gemini CLI 可观察性指南

¥Gemini CLI Observability Guide

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

¥Telemetry provides data about Gemini CLI's performance, health, and usage. By enabling it, you can monitor operations, debug issues, and optimize tool usage through traces, metrics, and structured logs.

Gemini CLI 的遥测系统建立在开放遥测（酒店）标准，允许您将数据发送到任何兼容的后端。

¥Gemini CLI's telemetry system is built on the OpenTelemetry (OTEL) standard, allowing you to send data to any compatible backend.

启用遥测

¥Enabling telemetry

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

¥You can enable telemetry in multiple ways. Configuration is primarily managed via the .gemini/settings.json file and environment variables, but CLI flags can override these settings for a specific session.

优先顺序

¥Order of precedence

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

¥The following lists the precedence for applying telemetry settings, with items listed higher having greater precedence:

1. CLI 标志（用于gemini命令）：

   ¥CLI flags (for gemini command):

   • --telemetry/--no-telemetry：覆盖telemetry.enabled。

     ¥--telemetry / --no-telemetry: Overrides telemetry.enabled.

   • --telemetry-target <local|gcp>：覆盖telemetry.target。

     ¥--telemetry-target <local|gcp>: Overrides telemetry.target.

   • --telemetry-otlp-endpoint <URL>：覆盖telemetry.otlpEndpoint。

     ¥--telemetry-otlp-endpoint <URL>: Overrides telemetry.otlpEndpoint.

   • --telemetry-log-prompts/--no-telemetry-log-prompts：覆盖telemetry.logPrompts。

     ¥--telemetry-log-prompts / --no-telemetry-log-prompts: Overrides telemetry.logPrompts.

   • --telemetry-outfile <path>：将遥测输出重定向到文件。请参阅导出到文件。

     ¥--telemetry-outfile <path>: Redirects telemetry output to a file. See Exporting to a file.

2. 环境变量：

   ¥Environment variables:

   • OTEL_EXPORTER_OTLP_ENDPOINT：覆盖telemetry.otlpEndpoint。

     ¥OTEL_EXPORTER_OTLP_ENDPOINT: Overrides telemetry.otlpEndpoint.

3. 工作区设置文件（.gemini/settings.json):价值观来自telemetry此项目特定文件中的对象。

   ¥Workspace settings file (.gemini/settings.json): Values from the telemetry object in this project-specific file.

4. 用户设置文件（~/.gemini/settings.json):价值观来自telemetry此全局用户文件中的对象。

   ¥User settings file (~/.gemini/settings.json): Values from the telemetry object in this global user file.

5. 默认值：如果上述任何一项均未设置，则应用。

   ¥Defaults: applied if not set by any of the above.

   • telemetry.enabled：false

     ¥telemetry.enabled: false

   • telemetry.target：local

     ¥telemetry.target: local

   • telemetry.otlpEndpoint：http://localhost:4317

     ¥telemetry.otlpEndpoint: http://localhost:4317

   • telemetry.logPrompts：true

     ¥telemetry.logPrompts: true

对于npm run telemetry -- --target=<gcp|local>脚本：这--target该脚本的参数仅有的覆盖telemetry.target该脚本的持续时间和目的（即选择启动哪个收集器）。它不会永久改变您的settings.json.脚本首先会查看settings.json对于telemetry.target用作其默认值。

¥For the npm run telemetry -- --target=<gcp|local> script: The --target argument to this script only overrides the telemetry.target for the duration and purpose of that script (i.e., choosing which collector to start). It does not permanently change your settings.json. The script will first look at settings.json for a telemetry.target to use as its default.

示例设置

¥Example settings

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

¥The following code can be added to your workspace (.gemini/settings.json) or user (~/.gemini/settings.json) settings to enable telemetry and send the output to Google Cloud:

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

导出到文件

¥Exporting to a file

您可以将所有遥测数据导出到文件以供本地检查。

¥You can export all telemetry data to a file for local inspection.

要启用文件导出，请使用--telemetry-outfile带有所需输出文件的路径的标志。必须使用--telemetry-target=local。

¥To enable file export, use the --telemetry-outfile flag with a path to your desired output file. This must be run using --telemetry-target=local.

# Set your desired output file path
TELEMETRY_FILE=".gemini/telemetry.log"

# Run Gemini CLI with local telemetry
# NOTE: --telemetry-otlp-endpoint="" is required to override the default
# OTLP exporter and ensure telemetry is written to the local file.
gemini --telemetry \
  --telemetry-target=local \
  --telemetry-otlp-endpoint="" \
  --telemetry-outfile="$TELEMETRY_FILE" \
  --prompt "What is OpenTelemetry?"

运行 OTEL 收集器

¥Running an OTEL Collector

OTEL 收集器是一种接收、处理和导出遥测数据的服务。CLI 可以使用 OTLP/gRPC 或 OTLP/HTTP 协议发送数据。您可以通过--telemetry-otlp-protocol旗帜或telemetry.otlpProtocol在您的设置中settings.json文件。请参阅配置文档了解更多详情。

¥An OTEL Collector is a service that receives, processes, and exports telemetry data. The CLI can send data using either the OTLP/gRPC or OTLP/HTTP protocol. You can specify which protocol to use via the --telemetry-otlp-protocol flag or the telemetry.otlpProtocol setting in your settings.json file. See the configuration docs for more details.

详细了解 OTEL 导出器标准配置文档。

¥Learn more about OTEL exporter standard configuration in documentation.

当地的

¥Local

使用npm run telemetry -- --target=local命令自动执行设置本地遥测管道的过程，包括配置必要的设置.gemini/settings.json文件。底层脚本安装otelcol-contrib（OpenTelemetry 收集器）和jaeger（用于查看跟踪信息的 Jaeger UI）。使用方法：

¥Use the npm run telemetry -- --target=local command to automate the process of setting up a local telemetry pipeline, including configuring the necessary settings in your .gemini/settings.json file. The underlying script installs otelcol-contrib (the OpenTelemetry Collector) and jaeger (The Jaeger UI for viewing traces). To use it:

1. 运行命令：从存储库的根目录执行命令：

   ¥Run the command: Execute the command from the root of the repository:

   bash npm run telemetry -- --target=local

   ¥bash npm run telemetry -- --target=local

   该脚本将：- 如果需要，下载 Jaeger 和 OTEL。- 启动本地 Jaeger 实例。- 启动配置为从 Gemini CLI 接收数据的 OTEL 收集器。- 在工作区设置中自动启用遥测。- 退出时，禁用遥测。

   ¥The script will: - Download Jaeger and OTEL if needed. - Start a local Jaeger instance. - Start an OTEL collector configured to receive data from Gemini CLI. - Automatically enable telemetry in your workspace settings. - On exit, disable telemetry.

2. 查看跟踪：打开您的网络浏览器并导航至http://localhost:16686访问 Jaeger UI。在这里，您可以检查 Gemini CLI 操作的详细跟踪信息。

   ¥View traces: Open your web browser and navigate to http://localhost:16686 to access the Jaeger UI. Here you can inspect detailed traces of Gemini CLI operations.

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

   ¥Inspect logs and metrics: The script redirects the OTEL collector output (which includes logs and metrics) to ~/.gemini/tmp/<projectHash>/otel/collector.log. The script will provide links to view and a command to tail your telemetry data (traces, metrics, logs) locally.

4. 停止服务： 按Ctrl+C在运行脚本的终端中停止 OTEL Collector 和 Jaeger 服务。

   ¥Stop the services: Press Ctrl+C in the terminal where the script is running to stop the OTEL Collector and Jaeger services.

谷歌云

¥Google Cloud

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

¥Use the npm run telemetry -- --target=gcp command to automate setting up a local OpenTelemetry collector that forwards data to your Google Cloud project, including configuring the necessary settings in your .gemini/settings.json file. The underlying script installs otelcol-contrib. To use it:

1. 先决条件：

   ¥Prerequisites:

   • 拥有 Google Cloud 项目 ID。

     ¥Have a Google Cloud project ID.

   • 导出GOOGLE_CLOUD_PROJECT环境变量以使其可供 OTEL 收集器使用。bash export OTLP_GOOGLE_CLOUD_PROJECT="your-project-id"

     ¥Export the GOOGLE_CLOUD_PROJECT environment variable to make it available to the OTEL collector. bash export OTLP_GOOGLE_CLOUD_PROJECT="your-project-id"

   • 使用 Google Cloud 进行身份验证（例如，运行gcloud auth application-default login或确保GOOGLE_APPLICATION_CREDENTIALS已设置）。

     ¥Authenticate with Google Cloud (e.g., run gcloud auth application-default login or ensure GOOGLE_APPLICATION_CREDENTIALS is set).

   • 确保您的 Google Cloud 帐户/服务帐户具有必要的 IAM 角色：“Cloud Trace Agent”、“Monitoring Metric Writer”和“Logs Writer”。

     ¥Ensure your Google Cloud account/service account has the necessary IAM roles: "Cloud Trace Agent", "Monitoring Metric Writer", and "Logs Writer".

2. 运行命令：从存储库的根目录执行命令：

   ¥Run the command: Execute the command from the root of the repository:

   bash npm run telemetry -- --target=gcp

   ¥bash npm run telemetry -- --target=gcp

   该脚本将： - 下载otelcol-contrib如果需要，请提供二进制文件。 - 启动配置为从 Gemini CLI 接收数据的 OTEL 收集器并将其导出到您指定的 Google Cloud 项目。 - 在您的工作区设置中自动启用遥测并禁用沙盒模式（.gemini/settings.json)。- 提供直接链接以查看 Google Cloud Console 中的跟踪、指标和日志。- 退出（Ctrl+C）时，它将尝试恢复您的原始遥测和沙盒设置。

   ¥The script will: - Download the otelcol-contrib binary if needed. - Start an OTEL collector configured to receive data from Gemini CLI and export it to your specified Google Cloud project. - Automatically enable telemetry and disable sandbox mode in your workspace settings (.gemini/settings.json). - Provide direct links to view traces, metrics, and logs in your Google Cloud Console. - On exit (Ctrl+C), it will attempt to restore your original telemetry and sandbox settings.

3. 运行 Gemini CLI：在单独的终端中，运行 Gemini CLI 命令。这将生成收集器捕获的遥测数据。

   ¥Run Gemini CLI: In a separate terminal, run your Gemini CLI commands. This generates telemetry data that the collector captures.

4. 在 Google Cloud 中查看遥测数据：使用脚本提供的链接导航到 Google Cloud Console 并查看您的跟踪、指标和日志。

   ¥View telemetry in Google Cloud: Use the links provided by the script to navigate to the Google Cloud Console and view your traces, metrics, and logs.

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

   ¥Inspect local collector logs: The script redirects the local OTEL collector output to ~/.gemini/tmp/<projectHash>/otel/collector-gcp.log. The script provides links to view and command to tail your collector logs locally.

6. 停止服务： 按Ctrl+C在运行脚本的终端中停止 OTEL Collector。

   ¥Stop the service: Press Ctrl+C in the terminal where the script is running to stop the OTEL Collector.

日志和指标参考

¥Logs and metric reference

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

¥The following section describes the structure of logs and metrics generated for Gemini CLI.

• 一个sessionId包含在所有日志和指标中作为通用属性。

  ¥A sessionId is included as a common attribute on all logs and metrics.

日志

¥Logs

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

¥Logs are timestamped records of specific events. The following events are logged for Gemini CLI:

• gemini_cli.config：此事件在启动时使用 CLI 的配置发生一次。

  ¥gemini_cli.config: This event occurs once at startup with the CLI's configuration.

• 属性：

  ¥Attributes:

  • model（细绳）

    ¥model (string)

  • embedding_model（细绳）

    ¥embedding_model (string)

  • sandbox_enabled（布尔值）

    ¥sandbox_enabled (boolean)

  • core_tools_enabled（细绳）

    ¥core_tools_enabled (string)

  • approval_mode（细绳）

    ¥approval_mode (string)

  • api_key_enabled（布尔值）

    ¥api_key_enabled (boolean)

  • vertex_ai_enabled（布尔值）

    ¥vertex_ai_enabled (boolean)

  • code_assist_enabled（布尔值）

    ¥code_assist_enabled (boolean)

  • log_prompts_enabled（布尔值）

    ¥log_prompts_enabled (boolean)

  • file_filtering_respect_git_ignore（布尔值）

    ¥file_filtering_respect_git_ignore (boolean)

  • debug_mode（布尔值）

    ¥debug_mode (boolean)

  • mcp_servers（细绳）

    ¥mcp_servers (string)

• gemini_cli.user_prompt：当用户提交提示时发生此事件。

  ¥gemini_cli.user_prompt: This event occurs when a user submits a prompt.

• 属性：

  ¥Attributes:

  • prompt_length

    ¥prompt_length

  • prompt（如果log_prompts_enabled配置为false)

    ¥prompt (this attribute is excluded if log_prompts_enabled is configured to be false)

  • auth_type

    ¥auth_type

• gemini_cli.tool_call：每次函数调用时都会发生此事件。

  ¥gemini_cli.tool_call: This event occurs for each function call.

• 属性：

  ¥Attributes:

  • function_name

    ¥function_name

  • function_args

    ¥function_args

  • duration_ms

    ¥duration_ms

  • success（布尔值）

    ¥success (boolean)

  • decision（如果适用，字符串：“accept”、“reject”、“auto_accept”或“modify”）

    ¥decision (string: "accept", "reject", "auto_accept", or "modify", if applicable)

  • error（如适用）

    ¥error (if applicable)

  • error_type（如适用）

    ¥error_type (if applicable)

  • metadata（如果适用，字符串字典->任何）

    ¥metadata (if applicable, dictionary of string -> any)

• gemini_cli.api_request：向 Gemini API 发出请求时发生此事件。

  ¥gemini_cli.api_request: This event occurs when making a request to Gemini API.

• 属性：

  ¥Attributes:

  • model

    ¥model

  • request_text（如适用）

    ¥request_text (if applicable)

• gemini_cli.api_error：如果 API 请求失败，则会发生此事件。

  ¥gemini_cli.api_error: This event occurs if the API request fails.

• 属性：

  ¥Attributes:

  • model

    ¥model

  • error

    ¥error

  • error_type

    ¥error_type

  • status_code

    ¥status_code

  • duration_ms

    ¥duration_ms

  • auth_type

    ¥auth_type

• gemini_cli.api_response：收到 Gemini API 的响应时发生此事件。

  ¥gemini_cli.api_response: This event occurs upon receiving a response from Gemini API.

• 属性：

  ¥Attributes:

  • model

    ¥model

  • status_code

    ¥status_code

  • duration_ms

    ¥duration_ms

  • error（选修的）

    ¥error (optional)

  • input_token_count

    ¥input_token_count

  • output_token_count

    ¥output_token_count

  • cached_content_token_count

    ¥cached_content_token_count

  • thoughts_token_count

    ¥thoughts_token_count

  • tool_token_count

    ¥tool_token_count

  • response_text（如适用）

    ¥response_text (if applicable)

  • auth_type

    ¥auth_type

• gemini_cli.malformed_json_response：此事件发生在generateJson无法将 Gemini API 的响应解析为 json。

  ¥gemini_cli.malformed_json_response: This event occurs when a generateJson response from Gemini API cannot be parsed as a json.

• 属性：

  ¥Attributes:

  • model

    ¥model

• gemini_cli.flash_fallback：当 Gemini CLI 切换到闪存作为后备时，会发生此事件。

  ¥gemini_cli.flash_fallback: This event occurs when Gemini CLI switches to flash as fallback.

• 属性：

  ¥Attributes:

  • auth_type

    ¥auth_type

• gemini_cli.slash_command：当用户执行斜线命令时会发生此事件。

  ¥gemini_cli.slash_command: This event occurs when a user executes a slash command.

• 属性：

  ¥Attributes:

  • command（细绳）

    ¥command (string)

  • subcommand（字符串，如果适用）

    ¥subcommand (string, if applicable)

指标

¥Metrics

指标是对一段时间内的行为进行数值测量。Gemini CLI 收集以下指标：

¥Metrics are numerical measurements of behavior over time. The following metrics are collected for Gemini CLI:

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

  ¥gemini_cli.session.count (Counter, Int): Incremented once per CLI startup.

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

  ¥gemini_cli.tool.call.count (Counter, Int): Counts tool calls.

• 属性：

  ¥Attributes:

  • function_name

    ¥function_name

  • success（布尔值）

    ¥success (boolean)

  • decision（字符串：“接受”、“拒绝”或“修改”，如果适用）

    ¥decision (string: "accept", "reject", or "modify", if applicable)

  • tool_type（如果适用，字符串：“mcp”或“native”）

    ¥tool_type (string: "mcp", or "native", if applicable)

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

  ¥gemini_cli.tool.call.latency (Histogram, ms): Measures tool call latency.

• 属性：

  ¥Attributes:

  • function_name

    ¥function_name

  • decision（字符串：“接受”、“拒绝”或“修改”，如果适用）

    ¥decision (string: "accept", "reject", or "modify", if applicable)

• gemini_cli.api.request.count（计数器，Int）：计算所有 API 请求数。

  ¥gemini_cli.api.request.count (Counter, Int): Counts all API requests.

• 属性：

  ¥Attributes:

  • model

    ¥model

  • status_code

    ¥status_code

  • error_type（如适用）

    ¥error_type (if applicable)

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

  ¥gemini_cli.api.request.latency (Histogram, ms): Measures API request latency.

• 属性：

  ¥Attributes:

  • model

    ¥model

• gemini_cli.token.usage（计数器，Int）：计算使用的令牌数量。

  ¥gemini_cli.token.usage (Counter, Int): Counts the number of tokens used.

• 属性：

  ¥Attributes:

  • model

    ¥model

  • type（字符串：“输入”、“输出”、“思想”、“缓存”或“工具”）

    ¥type (string: "input", "output", "thought", "cache", or "tool")

• gemini_cli.file.operation.count（计数器，Int）：计算文件操作数。

  ¥gemini_cli.file.operation.count (Counter, Int): Counts file operations.

• 属性：

  ¥Attributes:

  • operation(字符串：“create”、“read”、“update”）：文件操作的类型。

    ¥operation (string: "create", "read", "update"): The type of file operation.

  • lines（如果适用，则为整数）：文件中的行数。

    ¥lines (Int, if applicable): Number of lines in the file.

  • mimetype（字符串，如果适用）：文件的 Mimetype。

    ¥mimetype (string, if applicable): Mimetype of the file.

  • extension（字符串，如果适用）：文件的文件扩展名。

    ¥extension (string, if applicable): File extension of the file.

  • ai_added_lines（如果适用，则为整数）：AI 添加/更改的行数。

    ¥ai_added_lines (Int, if applicable): Number of lines added/changed by AI.

  • ai_removed_lines（如果适用，则为整数）：AI 删除/更改的行数。

    ¥ai_removed_lines (Int, if applicable): Number of lines removed/changed by AI.

  • user_added_lines（整数，如果适用）：用户在 AI 建议的更改中添加/更改的行数。

    ¥user_added_lines (Int, if applicable): Number of lines added/changed by user in AI proposed changes.

  • user_removed_lines（整数，如果适用）：AI 建议的更改中用户删除/更改的行数。

    ¥user_removed_lines (Int, if applicable): Number of lines removed/changed by user in AI proposed changes.

  • programming_language（字符串，如果适用）：文件的编程语言。

    ¥programming_language (string, if applicable): The programming language of the file.

• gemini_cli.chat_compression(Counter, Int)：统计聊天压缩操作

  ¥gemini_cli.chat_compression (Counter, Int): Counts chat compression operations

• 属性：

  ¥Attributes:

  • tokens_before：（Int）：压缩前上下文中的标记数

    ¥tokens_before: (Int): Number of tokens in context prior to compression

  • tokens_after：（Int）：压缩后上下文中的标记数

    ¥tokens_after: (Int): Number of tokens in context after compression