使用 OpenTelemetry 进行可观测性

使用 OpenTelemetry 进行可观测性

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

• 使用 OpenTelemetry 进行可观测性
  • 主要优势
  • OpenTelemetry 集成
  • 配置
  • Google Cloud 遥测
    • 先决条件
    • 直接导出（推荐）
    • 基于收集器的导出（高级）
  • 本地遥测
    • 基于文件的输出（推荐）
    • 基于收集器的导出（高级）
  • 日志和指标
    • 日志
      • 会话
      • 工具
      • 文件
      • API
      • 模型路由
      • 聊天和流式处理
      • 弹性
      • 扩展
      • 代理运行
      • IDE
      • UI
    • 指标
      • 自定义
        • 会话
        • 工具
        • API
        • 令牌使用
        • 文件
        • 聊天和流式处理
        • 模型路由
        • 代理运行
        • UI
        • 性能
      • GenAI 语义约定

主要优势

（以下内容需等待原文提供后继续翻译）

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

OpenTelemetry 集成

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

• 通用兼容性：导出到任何 OpenTelemetry 后端（Google Cloud、Jaeger、Prometheus、Datadog 等）
• 标准化数据：在整个工具链中使用一致的数据格式和收集方法
• 面向未来的集成：与现有和未来的可观测性基础设施连接
• 无厂商锁定：在不更改仪器的情况下切换后端

配置

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

设置	环境变量	描述	值	默认
telemetry	TELEMETRY	启用或禁用遥测	true/false	默认值
telemetry_url	TELEMETRY_URL	发送遥测数据的位置	URL字符串/禁用	默认值
otlp_collector_endpoint	OTLP_COLLECTOR_ENDPOINT	OTLP收集器端点	URL字符串	默认值
otlp_transport_protocol	OTLP_TRANSPORT_PROTOCOL	OTLP传输协议	协议/禁用	默认值
telemetry_file	TELEMETRY_FILE	将遥测保存到文件（覆盖默认值）	文件路径	-
include_prompts	INCLUDE_PROMPTS	在遥测日志中包含提示	true/false	默认值
use_external_otlp_collector	USE_EXTERNAL_OTLP_COLLECTOR	使用外部OTLP收集器（高级）	true/false	默认值
use_cli_credentials	USE_CLI_CREDENTIALS	使用CLI凭据进行遥测（仅限GCP目标）	true/false	默认值

关于布尔环境变量的说明： 对于布尔设置（TELEMETRY_ENABLED、TELEMETRY_URL_ENABLED、INCLUDE_PROMPTS），将对应的环境变量设置为”true”或”false”将启用该功能。任何其他值都将禁用它。

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

Google Cloud遥测

先决条件

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

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角色：

   • 云跟踪代理
   • 监控指标写入者
   • 日志写入者

4. 启用所需的Google CloudAPI（如尚未启用）：

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

使用CLI凭证认证

默认情况下，Google Cloud的遥测收集器使用应用程序默认凭证（ADC）。但是，您可以将其配置为使用与登录Gemini CLI相同的OAuth凭证。这在您没有设置ADC的环境中非常有用。

要启用此功能，请在您的telemetry设置中将useCliAuth属性设置为true：

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

重要：

• 此设置需要使用直接导出（进程内导出器）。
• 它不能与useCollector: true一起使用。如果同时启用两者，遥测将被禁用，并且会记录错误。
• CLI将自动使用您的凭证与Google Cloud跟踪、指标和日志API进行认证。

直接导出（推荐）

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

【翻译文本】

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

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

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

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

对于自定义处理、过滤或路由，请使用 OpenTelemetry 收集器将数据转发到 Google Cloud。

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

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

2. 运行自动化脚本：

   npm run telemetry -- --target=gcp

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

本地遥测

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

基于文件的输出（推荐）

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

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

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

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

1. 运行自动化脚本：

   npm run telemetry -- --target=local

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

日志和指标

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

session.id、installation.id 和 user.email（仅当使用 Google 帐户认证时可用）作为所有日志和指标的通用属性包含在内。

日志

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

会话

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

• gemini_cli.config：在启动时发出一次，带有 CLI 配置。

  • 属性：
    • model（字符串）
    • embedding_model（字符串）
    • sandbox_enabled（布尔值）
    • core_tools_enabled（字符串）
    • approval_mode（字符串）
    • api_key_enabled（布尔值）
    • vertex_ai_enabled（布尔值）
    • log_user_prompts_enabled（布尔值）
    • file_filtering_respect_git_ignore（布尔值）
    • debug_mode（布尔值）
    • mcp_servers（字符串）
    • mcp_servers_count（整数）
    • extensions（字符串）
    • extension_ids（字符串）
    • extension_count（整数）
    • mcp_tools（如果适用，字符串）
    • mcp_tools_count（如果适用，整数）
    • output_format（“text”、“json” 或 “stream-json”）

• gemini_cli.user_prompt：当用户提交提示时发出。

  • 属性：
    • prompt_length（整数）
    • prompt_id（字符串）
    • prompt（字符串；如果 telemetry.logPrompts 是 false，则排除）
    • auth_type（字符串）

工具

捕获工具执行、输出截断和编辑行为。

• 每个工具（函数）调用都会触发 gemini_cli.tool_call。

  • 属性：
    • function_name
    • function_args
    • duration_ms
    • success（布尔值）
    • decision（“accept”、“reject”、“auto_accept” 或 “modify”，如果适用）
    • error（如果适用）
    • error_type（如果适用）
    • prompt_id（字符串）
    • tool_type（“native” 或 “mcp”）
    • mcp_server_name（如果适用，字符串）
    • extension_name（如果适用，字符串）
    • extension_id（如果适用，字符串）
    • content_length（如果适用，整数）
    • metadata（如果适用）

• 工具调用的输出被截断 gemini_cli.tool_output_truncated。

  • 属性：
    • tool_name（字符串）
    • original_content_length（整数）
    • truncated_content_length（整数）
    • threshold（整数）
    • lines（整数）
    • prompt_id（字符串）

• 选择的编辑策略 gemini_cli.edit_strategy。

  • 属性：
    • strategy（字符串）

• 编辑修正结果 gemini_cli.edit_correction。

  • 属性：
    • correction（“success” | “failure”）

• 此事件提供了关于 GenAI 操作的详细信息，与 [OpenTelemetry GenAI 语义约定事件] 保持一致 gen_ai.client.inference.operation.details。

  • 属性：
    • gen_ai.request.model（字符串）
    • gen_ai.provider.name（字符串）
    • gen_ai.operation.name（字符串）
    • gen_ai.input.messages（JSON 字符串）
    • gen_ai.output.messages（JSON 字符串）
    • gen_ai.response.finish_reasons（字符串数组）
    • gen_ai.usage.input_tokens（整数）
    • gen_ai.usage.output_tokens（整数）
    • gen_ai.request.temperature（浮点数）
    • gen_ai.request.top_p（浮点数）
    • gen_ai.request.top_k（整数）
    • gen_ai.request.max_tokens（整数）
    • gen_ai.system_instructions（JSON 字符串）
    • server.address（字符串）
    • server.port（整数）

文件

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

---

对于给定的 Markdown 文档片段，以下是翻译后的简体中文文本：

---

对于文件操作，将发出以下事件。

• 属性：
  • tool_name （字符串）
  • operation （“create” | “read” | “update”）
  • lines （整数，可选）
  • mimetype （字符串，可选）
  • extension （字符串，可选）
  • programming_language （字符串，可选）

API

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

• gemini_cli.api_request：发送到 Gemini API 的请求。

  • 属性：
    • model （字符串）
    • prompt_id （字符串）
    • request_text （字符串，可选）

• gemini_cli.api_response：从 Gemini API 收到的响应。

  • 属性：
    • model （字符串）
    • status_code （整数或字符串）
    • duration_ms （整数）
    • input_token_count （整数）
    • output_token_count （整数）
    • cached_content_token_count （整数）
    • thoughts_token_count （整数）
    • tool_token_count （整数）
    • total_token_count （整数）
    • response_text （字符串，可选）
    • prompt_id （字符串）
    • auth_type （字符串）
    • finish_reasons （字符串数组）

• gemini_cli.api_error：API 请求失败。

  • 属性：
    • model （字符串）
    • error （字符串）
    • error_type （字符串）
    • status_code （整数或字符串）
    • duration_ms （整数）
    • prompt_id （字符串）
    • auth_type （字符串）

• gemini_cli.malformed_json_response：无法解析 generateJson 响应。

  • 属性：
    • model （字符串）

模型路由

• gemini_cli.slash_command：执行了斜杠命令。

  • 属性：
    • command （字符串）
    • subcommand （字符串，可选）
    • status （“success” | “error”）

• gemini_cli.slash_command.model：通过斜杠命令选择了模型。

  • 属性：
    • model_name （字符串）

---

请注意，根据您的要求，代码块和特殊标记已被保留，并且没有翻译。

【翻译】

• 模型路由器做出了决策。
  • 属性：
    • decision_model（字符串）
    • decision_source（字符串）
    • routing_latency_ms（整数）
    • reasoning（字符串，可选）
    • failed（布尔值）
    • error_message（字符串，可选）

聊天与流式

• 聊天上下文被压缩。

  • 属性：
    • tokens_before（整数）
    • tokens_after（整数）

• 从流中接收到无效的分块。

  • 属性：
    • error.message（字符串，可选）

• 由于内容错误触发了重试。

  • 属性：
    • attempt_number（整数）
    • error_type（字符串）
    • retry_delay_ms（整数）
    • model（字符串）

• 所有内容重试失败。

  • 属性：
    • total_attempts（整数）
    • final_error_type（字符串）
    • total_duration_ms（整数，可选）
    • model（字符串）

• 对话会话结束。

  • 属性：
    • approvalMode（字符串）
    • turnCount（整数）

• 确定下一个发言者。

  • 属性：
    • prompt_id（字符串）
    • finish_reason（字符串）
    • result（字符串）

健壮性

记录模型和网络操作的降级机制。

• 切换到快闪模型作为降级。

  • 属性：
    • auth_type（字符串）

• 切换到 grep 作为文件搜索的降级。

  • 属性：
    • error（字符串，可选）

• 尝试 web-fetch 降级。

  • 属性：
    • reason（“private_ip” | “primary_failed”）

扩展

跟踪扩展的生命周期和设置更改。

【译文】

• 扩展已安装。

  • 属性：
    • extension_name (字符串)
    • extension_version (字符串)
    • extension_source (字符串)
    • status (字符串)

• 扩展已卸载。

  • 属性：
    • extension_name (字符串)
    • status (字符串)

• 扩展已启用。

  • 属性：
    • extension_name (字符串)
    • setting_scope (字符串)

• 扩展已禁用。

  • 属性：
    • extension_name (字符串)
    • setting_scope (字符串)

• 扩展已更新。

  • 属性：
    • extension_name (字符串)
    • extension_version (字符串)
    • extension_previous_version (字符串)
    • extension_source (字符串)
    • status (字符串)

代理运行

• 代理运行开始。

  • 属性：
    • agent_id (字符串)
    • agent_name (字符串)

• 代理运行结束。

  • 属性：
    • agent_id (字符串)
    • agent_name (字符串)
    • duration_ms (整数)
    • turn_count (整数)
    • terminate_reason (字符串)

IDE

捕获 IDE 连接性和对话生命周期事件。

• IDE 伴侣连接。
  • 属性：
    • connection_type (字符串)

UI

跟踪终端渲染问题及相关信号。

• 终端 kitty 控制序列溢出。
  • 属性：
    • sequence_length (整数)
    • truncated_sequence (字符串)

指标

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

自定义

会话

统计 CLI 启动时的会话数。

• gemini_cli.session.count (计数器，整数)：每次 CLI 启动时增加一次。

工具

测量工具使用和延迟。

【术语表】

• CLI: CLI（命令行界面）
• command-line interface: 命令行界面
• Shell: Shell
• Bash: Bash
• API: API
• endpoint: 端点
• token: 令牌
• Model Context Protocol: 模型上下文协议（MCP）
• MCP: MCP
• Markdown: Markdown
• JSON: JSON
• YAML: YAML
• Mermaid: Mermaid
• npm: npm
• pip: pip
• git: git
• repository: 仓库
• package: 包
• dependency: 依赖
• configuration: 配置
• environment variable: 环境变量
• workspace: 工作空间
• directory: 目录
• file: 文件
• script: 脚本
• plugin: 插件
• extension: 扩展
• integration: 集成
• authentication: 认证
• authorization: 授权
• credential: 凭证
• session: 会话
• context: 上下文
• prompt: 提示词
• completion: 补全
• streaming: 流式
• model: 模型
• provider: 提供商
• service: 服务
• request: 请求
• response: 响应
• header: 头部
• body: 主体
• payload: 负载
• error: 错误
• exception: 异常
• warning: 警告
• debug: 调试
• logging: 日志
• telemetry: 遥测
• analytics: 分析
• monitoring: 监控
• performance: 性能
• latency: 延迟
• throughput: 吞吐量
• concurrency: 并发
• thread: 线程
• process: 进程
• daemon: 守护进程
• background: 背景
• foreground: 前台
• interactive: 交互式
• batch: 批处理
• queue: 队列
• cache: 缓存
• database: 数据库
• storage: 存储
• memory: 内存
• disk: 磁盘
• network: 网络
• protocol: 协议
• HTTP: HTTP
• HTTPS: HTTPS
• WebSocket: WebSocket
• REST: REST
• GraphQL: GraphQL
• RPC: RPC
• SDK: SDK
• library: 库
• framework: 框架
• runtime: 运行时
• build: 构建
• deploy: 部署
• release: 发布
• version: 版本
• changelog: 更新日志
• migration: 迁移
• compatibility: 兼容性
• breaking change: 破坏性变更
• feature: 功能
• bug fix: 错误修复
• improvement: 改进
• enhancement: 增强
• refactor: 重构
• documentation: 文档
• tutorial: 教程
• example: 示例
• demo: 演示
• test: 测试
• unit test: 单元测试

【原文】

• 计数器（整数）: 计数工具调用次数。

  • 属性:
    • 占位符function_name
    • 占位符success（布尔值）
    • 占位符decision（字符串：“accept”、“reject”、“modify” 或 “auto_accept”，如果适用）
    • 占位符tool_type（字符串：“mcp” 或 “native”，如果适用）

• 直方图（毫秒）: 测量工具调用延迟。

  • 属性:
    • 占位符function_name

API

跟踪 API 请求量和延迟。

• 计数器（整数）: 计数所有 API 请求。

  • 属性:
    • 占位符model
    • 占位符status_code
    • 占位符error_type（如果适用）

• 直方图（毫秒）: 测量 API 请求延迟。

  • 属性:
    • 占位符model
  • 注意：与占位符gen_ai.client.operation.duration（GenAI 约定）重叠。

令牌使用

跟踪模型和类型的令牌使用情况。

• 计数器（整数）: 计数使用的令牌。
  • 属性:
    • 占位符model
    • 占位符type（“input”、“output”、“thought”、“cache” 或 “tool”）

【翻译】

• 计数器，整型（Counter, Int）：统计流中的无效数据块。

• 计数器，整型（Counter, Int）：因内容错误而重试的次数。

• 计数器，整型（Counter, Int）：统计所有内容重试失败的请求。

模型路由

统计模型路由的延迟/失败和斜杠命令选择。

• 计数器，整型（Counter, Int）：通过斜杠命令选择模型的次数。

  • 属性：
    • 字符串（string）

• 直方图，毫秒（Histogram, ms）：模型路由决策的延迟。

  • 属性：
    • 字符串（string）
    • 字符串（string）

• 计数器，整型（Counter, Int）：统计模型路由失败的次数。

  • 属性：
    • 字符串（string）
    • 字符串（string）

代理运行

代理生命周期指标：运行次数、持续时间和轮次。

• 计数器，整型（Counter, Int）：统计代理运行次数。

  • 属性：
    • 字符串（string）
    • 字符串（string）

• 直方图，毫秒（Histogram, ms）：代理运行持续时间。

  • 属性：
    • 字符串（string）

• 直方图，轮次（Histogram, turns）：每次代理运行的轮次。

  • 属性：
    • 字符串（string）

用户界面

用户界面稳定性信号，例如闪烁计数。

• 计数器，整型（Counter, Int）：统计UI帧闪烁次数（渲染高于终端高度）。

性能

可选的性能监控，包括启动、CPU/内存和阶段计时。

• 直方图，毫秒（Histogram, ms）：按阶段统计CLI启动时间。

  • 属性：
    • 字符串（string）
    • 映射（可选，map, optional）

• 直方图，字节（Histogram, bytes）：内存使用情况。

  • 属性：
    • “heap_used”, “heap_total”, “external”, “rss”
    • 字符串（可选，string, optional）

• 直方图，百分比（Histogram, percent）：CPU使用百分比。

  • 属性：
    • 字符串（可选，string, optional）

• 执行队列中的工具数量（直方图，计数）。

• 按阶段划分的工具时间（直方图，毫秒）。

  • 属性：
    • function_name (字符串)
    • phase (“validation”, “preparation”, “execution”, “result_processing”)

• 按阶段划分的API请求时间（直方图，毫秒）。

  • 属性：
    • model (字符串)
    • phase (“request_preparation”, “network_latency”, “response_processing”, “token_processing”)

• 令牌效率指标（直方图，比率）。

  • 属性：
    • model (字符串)
    • metric (字符串)
    • context (字符串，可选)

• 复合性能得分（直方图，分数）。

  • 属性：
    • category (字符串)
    • baseline (数字，可选)

• 回归检测事件（计数器，整型）。

  • 属性：
    • metric (字符串)
    • severity (“low”, “medium”, “high”)
    • current_value (数字)
    • baseline_value (数字)

• 当检测到回归时的基线变化百分比（直方图，百分比）。

  • 属性：
    • metric (字符串)
    • severity (“low”, “medium”, “high”)
    • current_value (数字)
    • baseline_value (数字)

• 与基线比较（直方图，百分比）。

  • 属性：
    • metric (字符串)
    • category (字符串)
    • current_value (数字)
    • baseline_value (数字)

GenAI语义约定

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

• 每个操作使用的输入和输出令牌数量（直方图，令牌）。

  • 属性：
    • 操作类型（字符串）：例如，“generate_content”、“chat”
    • GenAI提供商（字符串）：“gcp.gen_ai”或“gcp.vertex_ai”
    • 令牌类型（字符串）：“input”或“output”
    • 请求所用的模型名称（字符串，可选）
    • 生成响应的模型名称（字符串，可选）
    • GenAI服务器地址（字符串，可选）
    • GenAI服务器端口（整数，可选）

• GenAI操作持续时间直方图（秒）。

  • 属性：
    • 操作类型（字符串）：例如，“generate_content”、“chat”
    • GenAI提供商（字符串）：“gcp.gen_ai”或“gcp.vertex_ai”
    • 请求所用的模型名称（字符串，可选）
    • 生成响应的模型名称（字符串，可选）
    • GenAI服务器地址（字符串，可选）
    • GenAI服务器端口（整数，可选）
    • 如果操作失败，错误类型（字符串，可选）

[OpenTelemetry GenAI语义约定]： https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-metrics.md [OpenTelemetry GenAI事件语义约定]： https://github.com/open-telemetry/semantic-conventions/blob/8b4f210f43136e57c1f6f47292eb6d38e3bf30bb/docs/gen-ai/gen-ai-events.md