跳到主要内容

追踪 Gemini CLI

Gemini CLI Tracing via OpenTelemetry

MLflow Tracing 为 Google 的开源终端编程代理 Gemini CLI 提供自动追踪功能。Gemini CLI 内置了 OpenTelemetry 支持，可将丰富的对话追踪信息直接发送到 MLflow 的 OTLP 端点。追踪功能会自动捕获：

  • 用户提示词和助手回复（包括思考/推理过程）
  • 包含模型名称、令牌用量和成本的 LLM 调用
  • 工具调用及其结果
  • 会话元数据

设置​

Gemini CLI 的追踪数据通过其原生的 OTLP 遥测技术进行摄取——无需使用 MLflow CLI 命令。

要求​

  • MLflow 追踪服务器（已启用 OTLP 端点）
  • 已安装 Gemini CLI (npm install -g @google/gemini-cli)
  • Node.js 22+

第 1 步：设置环境变量​

bash
# Enable Gemini telemetry and point it at MLflow
export GEMINI_TELEMETRY_ENABLED=true
export GEMINI_TELEMETRY_TARGET=local
export GEMINI_TELEMETRY_OTLP_ENDPOINT=https://:5000
export GEMINI_TELEMETRY_OTLP_PROTOCOL=http

# Set the MLflow experiment ID via standard OTLP headers
export OTEL_EXPORTER_OTLP_HEADERS=x-mlflow-experiment-id=0

第 2 步：运行 Gemini CLI​

bash
# Tracing happens automatically
gemini

当您与 Gemini CLI 交互时，追踪数据会实时发送到 MLflow。

第 3 步：查看追踪信息​

bash
mlflow server
# Navigate to your experiment in the UI

配置参考​

环境变量必需描述
GEMINI_TELEMETRY_ENABLED是设置为 true 以启用遥测
GEMINI_TELEMETRY_TARGET是设置为 local 以使用自定义 OTLP 端点
GEMINI_TELEMETRY_OTLP_ENDPOINT是MLflow 服务器的基本 URL（例如 https://:5000）。Gemini 会自动附加 /v1/traces
GEMINI_TELEMETRY_OTLP_PROTOCOL是必须为 http（MLflow 不支持 gRPC 摄取）
OTEL_EXPORTER_OTLP_HEADERS是设置 x-mlflow-experiment-id=<id> 以将追踪数据路由到特定实验

配置示例​

bash
# Local MLflow server, default experiment
export GEMINI_TELEMETRY_ENABLED=true
export GEMINI_TELEMETRY_TARGET=local
export GEMINI_TELEMETRY_OTLP_ENDPOINT=https://:5000
export GEMINI_TELEMETRY_OTLP_PROTOCOL=http
export OTEL_EXPORTER_OTLP_HEADERS=x-mlflow-experiment-id=0

# Databricks-hosted MLflow
# See Databricks documentation for required authentication headers
export GEMINI_TELEMETRY_ENABLED=true
export GEMINI_TELEMETRY_TARGET=local
export GEMINI_TELEMETRY_OTLP_ENDPOINT=https://your-workspace.databricks.com
export GEMINI_TELEMETRY_OTLP_PROTOCOL=http
export OTEL_EXPORTER_OTLP_HEADERS=x-mlflow-experiment-id=123456789

工作原理​

Gemini CLI 使用 GenAI 语义约定发出 OpenTelemetry 追踪数据。MLflow 的 OTLP 端点摄取这些追踪数据并自动执行以下操作：

  1. 映射 span 类型：将 llm_call 映射为 LLM，tool_call 映射为 TOOL，agent_call 映射为 AGENT
  2. 提取令牌用量：从 gen_ai.usage.input_tokens 和 gen_ai.usage.output_tokens 中提取
  3. 计算成本：基于 gen_ai.request.model 中的模型名称进行计算
  4. 设置 service.name：将 gemini-cli 传播到根 span 以进行标识
  5. 在聊天 UI 中呈现：消息将显示在 MLflow 的聊天视图中，包含思考/推理部分

Token 使用与成本​

MLflow 会自动从 Gemini CLI 的 GenAI 语义约定属性中提取令牌用量，并根据模型计算成本。详情请参阅令牌用量与成本追踪文档。

故障排除​

没有显示追踪记录

  1. 确认协议设置为 http（而非 grpc）

    bash
    echo $GEMINI_TELEMETRY_OTLP_PROTOCOL  # Should be "http"

  2. 检查是否已设置实验 ID 标头

    bash
    echo $OTEL_EXPORTER_OTLP_HEADERS  # Should contain "x-mlflow-experiment-id=..."

  3. 检查 MLflow 服务器日志以查看是否有传入请求

    bash
    # Look for POST /v1/traces requests
    tail -f /tmp/mlflow-backend.log

400 Bad Request 错误

  • 确保已设置 GEMINI_TELEMETRY_OTLP_PROTOCOL=http。若未设置，Gemini 默认为 gRPC，而 MLflow 不支持此协议。

追踪信息显示但为空

  • Gemini CLI 发送混合的追踪数据。简单的提示词会产生 user_prompt + llm_call spans。涉及工具使用的复杂任务会产生包含 agent_call、tool_call 和多个 llm_call spans 的更丰富追踪数据。

禁用追踪​

取消设置遥测环境变量

bash
unset GEMINI_TELEMETRY_ENABLED
unset GEMINI_TELEMETRY_TARGET
unset GEMINI_TELEMETRY_OTLP_ENDPOINT

现有的追踪数据会被保留。