使用 OpenTelemetry 进行可观测性

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

• 使用 OpenTelemetry 进行可观测性
  • 主要优势
  • OpenTelemetry 集成
  • 配置
  • Google Cloud Telemetry
    • 先决条件
    • 直接导出（推荐）
    • 基于 Collector 的导出（高级）
  • 本地 Telemetry
    • 基于文件的输出（推荐）
    • 基于 Collector 的导出（高级）
  • 日志和指标
    • 日志
    • 指标
      • 自定义
      • GenAI 语义约定

主要优势

• 🔍 使用情况分析: 了解团队内的交互模式和功能采用情况
• ⚡ 性能监控: 跟踪响应时间、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"	"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"	"grpc"
outfile	GEMINI_TELEMETRY_OUTFILE	--telemetry-outfile <path>	将遥测数据保存到文件（覆盖 otlpEndpoint）	文件路径	-
logPrompts	GEMINI_TELEMETRY_LOG_PROMPTS	--telemetry-log-prompts / --no-telemetry-log-prompts	在遥测日志中包含提示	true/false	true
useCollector	GEMINI_TELEMETRY_USE_COLLECTOR	-	使用外部 OTLP collector（高级）	true/false	false

关于布尔环境变量的说明: 对于布尔设置（enabled、logPrompts、useCollector），将相应的环境变量设置为 true 或 1 将启用该功能。任何其他值都将禁用它。

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

Google Cloud Telemetry

先决条件

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

1. 设置您的 Google Cloud 项目 ID：

   • 对于与推理在不同项目中的遥测：

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

   • 对于与推理在同一项目中的遥测：

     export GOOGLE_CLOUD_PROJECT="your-project-id"

2. 使用 Google Cloud 进行身份验证：

   • 如果使用用户帐户：

     gcloud auth application-default login

   • 如果使用服务帐户：

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

3. 确保您的帐户或服务帐户具有以下 IAM 角色：

   • Cloud Trace Agent
   • Monitoring Metric Writer
   • Logs Writer

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

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

直接导出（推荐）

将遥测数据直接发送到 Google Cloud 服务。无需 collector。

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

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

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

基于 Collector 的导出（高级）

如需自定义处理、过滤或路由，请使用 OpenTelemetry collector 将数据转发到 Google Cloud。

1. 配置您的 .gemini/settings.json：

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

2. 运行自动化脚本：

   npm run telemetry -- --target=gcp

   这将：
   • 启动一个本地 OTEL collector，它会转发到 Google Cloud
   • 配置您的工作区
   • 提供指向 Google Cloud Console 中跟踪、指标和日志的链接
   • 将 collector 日志保存到 ~/.gemini/tmp/<projectHash>/otel/collector-gcp.log
   • 在退出时停止 collector（例如 Ctrl+C）
3. 运行 Gemini CLI 并发送提示。
4. 查看日志和指标：
   • 发送提示后，在浏览器中打开 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/tmp/<projectHash>/otel/collector-gcp.log 查看本地 collector 日志。

本地 Telemetry

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

基于文件的输出（推荐）

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

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

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

基于 Collector 的导出（高级）

1. 运行自动化脚本：

   npm run telemetry -- --target=local

   这将：
   • 下载并启动 Jaeger 和 OTEL collector
   • 配置您的工作区以进行本地遥测
   • 在 http://localhost:16686 提供 Jaeger UI
   • 将日志/指标保存到 ~/.gemini/tmp/<projectHash>/otel/collector.log
   • 在退出时停止 collector（例如 Ctrl+C）
2. 运行 Gemini CLI 并发送提示。
3. 在 http://localhost:16686 查看跟踪，并在 collector 日志文件中查看日志/指标。

日志和指标

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

• sessionId 作为所有日志和指标的通用属性包含在内。

日志

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

• gemini_cli.config: 此事件在启动时发生一次，包含 CLI 的配置。

  • 属性:
    • model (string)
    • embedding_model (string)
    • sandbox_enabled (boolean)
    • core_tools_enabled (string)
    • approval_mode (string)
    • api_key_enabled (boolean)
    • vertex_ai_enabled (boolean)
    • code_assist_enabled (boolean)
    • log_prompts_enabled (boolean)
    • file_filtering_respect_git_ignore (boolean)
    • debug_mode (boolean)
    • mcp_servers (string)
    • output_format (string: "text" 或 "json")

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

  • 属性:
    • prompt_length (int)
    • prompt_id (string)
    • prompt (string, 如果 log_prompts_enabled 配置为 false，则排除此属性)
    • auth_type (string)

• gemini_cli.tool_call: 对于每个函数调用都会发生此事件。

  • 属性:
    • function_name
    • function_args
    • duration_ms
    • success (boolean)
    • decision (string: "accept", "reject", "auto_accept", 或 "modify"，如果适用)
    • error (如果适用)
    • error_type (如果适用)
    • content_length (int, 如果适用)
    • metadata (如果适用, string -> any 的字典)

• gemini_cli.file_operation: 对于每个文件操作都会发生此事件。

  • 属性:
    • tool_name (string)
    • operation (string: "create", "read", "update")
    • lines (int, 如果适用)
    • mimetype (string, 如果适用)
    • extension (string, 如果适用)
    • programming_language (string, 如果适用)
    • diff_stat (json string, 如果适用): 一个 JSON 字符串，包含以下成员：
      • ai_added_lines (int)
      • ai_removed_lines (int)
      • user_added_lines (int)
      • user_removed_lines (int)

• gemini_cli.api_request: 调用 Gemini API 时发生此事件。

  • 属性:
    • model
    • request_text (如果适用)

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

  • 属性:
    • model
    • error
    • error_type
    • status_code
    • duration_ms
    • auth_type

• 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 (如果适用)
    • auth_type

• gemini_cli.tool_output_truncated: 当工具调用的输出过大而被截断时发生此事件。

  • 属性:
    • tool_name (string)
    • original_content_length (int)
    • truncated_content_length (int)
    • threshold (int)
    • lines (int)
    • prompt_id (string)

• gemini_cli.malformed_json_response: 当 Gemini API 的 generateJson 响应无法解析为 JSON 时发生此事件。

  • 属性:
    • model

• gemini_cli.flash_fallback: 当 Gemini CLI 切换到 flash 作为回退时发生此事件。

  • 属性:
    • auth_type

• gemini_cli.slash_command: 当用户执行斜杠命令时发生此事件。

  • 属性:
    • command (string)
    • subcommand (string, 如果适用)

• gemini_cli.extension_enable: 启用扩展时发生此事件

• gemini_cli.extension_install: 安装扩展时发生此事件

  • 属性:
    • extension_name (string)
    • extension_version (string)
    • extension_source (string)
    • status (string)

• gemini_cli.extension_uninstall: 卸载扩展时发生此事件

指标

指标是随时间推移的行为的数值测量。

自定义

• gemini_cli.session.count (计数器, Int): 每次 CLI 启动时递增。

• gemini_cli.tool.call.count (计数器, Int): 统计工具调用次数。

  • 属性:
    • function_name
    • success (boolean)
    • decision (string: "accept", "reject", 或 "modify", 如果适用)
    • tool_type (string: "mcp", 或 "native", 如果适用)

• gemini_cli.tool.call.latency (直方图, ms): 测量工具调用延迟。

  • 属性:
    • function_name
    • decision (string: "accept", "reject", 或 "modify", 如果适用)

• gemini_cli.api.request.count (计数器, Int): 统计所有 API 请求次数。

  • 属性:
    • model
    • status_code
    • error_type (如果适用)

• gemini_cli.api.request.latency (直方图, ms): 测量 API 请求延迟。

  • 属性:
    • model
  • 注意: 此指标与下面的 gen_ai.client.operation.duration 重叠，后者符合 GenAI 语义约定。

• gemini_cli.token.usage (计数器, Int): 统计使用的 Token 数量。

  • 属性:
    • model
    • type (string: "input", "output", "thought", "cache", 或 "tool")
  • 注意: 此指标与下面的 gen_ai.client.token.usage 重叠，后者针对 input/output Token 类型符合 GenAI 语义约定。

• gemini_cli.file.operation.count (计数器, Int): 统计文件操作次数。

  • 属性:
    • operation (string: "create", "read", "update"): 文件操作的类型。
    • lines (Int, 如果适用): 文件中的行数。
    • mimetype (string, 如果适用): 文件的 MIME 类型。
    • extension (string, 如果适用): 文件的扩展名。
    • model_added_lines (Int, 如果适用): 模型添加/更改的行数。
    • model_removed_lines (Int, 如果适用): 模型删除/更改的行数。
    • user_added_lines (Int, 如果适用): 用户在 AI 建议更改中添加/更改的行数。
    • user_removed_lines (Int, 如果适用): 用户在 AI 建议更改中删除/更改的行数。
    • programming_language (string, 如果适用): 文件的编程语言。

• gemini_cli.chat_compression (计数器, Int): 统计聊天压缩操作次数

  • 属性:
    • tokens_before: (Int): 压缩前上下文中的 Token 数量
    • tokens_after: (Int): 压缩后上下文中的 Token 数量

GenAI 语义约定

以下指标符合 [OpenTelemetry GenAI 语义约定]，可在 GenAI 应用程序中实现标准化可观测性：

• gen_ai.client.token.usage (直方图, token): 每次操作使用的输入和输出 Token 数量。

  • 属性:
    • gen_ai.operation.name (string): 操作类型（例如，“generate_content”、“chat”）
    • gen_ai.provider.name (string): GenAI 提供商（“gcp.gen_ai”或“gcp.vertex_ai”）
    • gen_ai.token.type (string): Token 类型（“input”或“output”）
    • gen_ai.request.model (string, 可选): 请求使用的模型名称
    • gen_ai.response.model (string, 可选): 生成响应的模型名称
    • server.address (string, 可选): GenAI 服务器地址
    • server.port (int, 可选): GenAI 服务器端口

• gen_ai.client.operation.duration (直方图, s): GenAI 操作持续时间（秒）。

  • 属性:
    • gen_ai.operation.name (string): 操作类型（例如，“generate_content”、“chat”）
    • gen_ai.provider.name (string): GenAI 提供商（“gcp.gen_ai”或“gcp.vertex_ai”）
    • gen_ai.request.model (string, 可选): 请求使用的模型名称
    • gen_ai.response.model (string, 可选): 生成响应的模型名称
    • server.address (string, 可选): GenAI 服务器地址
    • server.port (int, 可选): GenAI 服务器端口
    • error.type (string, 可选): 操作失败时的错误类型