追踪 Claude Code

MLflow Tracing 为 Claude Code CLI 提供自动追踪功能。配置完成后，项目中每一次 Claude Code 会话都会被记录到 MLflow 中，包含：

• 用户提示词 (User prompts) 和助手回复
• 工具调用（文件读取/编辑、bash、网络获取等）及其输入和输出
• 子代理（Subagent）调用及其运行的每个步骤的完整嵌套追踪
• 技能（Skill）使用情况
• 每次调用和每次会话的 Token 使用量及成本
• 每个步骤的延迟和耗时
• 会话元数据（工作目录、用户、模型）

正在使用 Claude Agent SDK 进行开发？

本页面涵盖 Claude Code CLI 的追踪。如果您是在 Claude Agent SDK 之上构建应用程序，请参阅 Claude Agent SDK (Python) 或 Claude Agent SDK (TypeScript)。

设置

启用 Claude Code 追踪有两种方法。请根据您的环境选择合适的方式：

Claude Code 插件（推荐）

MLflow Tracing 插件是启用追踪最简单的方法——它直接安装在 Claude Code 内部，不需要配备 MLflow 的本地 Python 环境。

第 1 步：添加 MLflow 插件市场

在你想要追踪的仓库中，从终端（而非 Claude Code 内部）运行以下命令：

bash

claude plugin marketplace add mlflow/mlflow --sparse .claude-plugin

警告

Claude 内部的 /plugin marketplace add 命令会克隆整个 mlflow/mlflow 仓库，往往会导致超时。请使用上面的终端命令并添加 --sparse .claude-plugin 参数。

第 2 步：安装插件

在终端执行：

bash

claude plugin install mlflow-tracing@mlflow-plugins

运行 claude 启动 Claude Code（如果已运行，请重启），以便加载插件。

第 3 步：运行设置命令

在 Claude Code 内部，运行插件的设置命令并按照向导操作，提供所需的值（跟踪 URI、实验名称、作用域）。

text

/mlflow-tracing:setup

第 4 步：确认配置

text

/mlflow-tracing:status

这将报告追踪功能是否已启用、当前活动的跟踪 URI、活动的实验，以及配置的来源作用域（environment、project、user 或 none）。

第 5 步：像往常一样使用 Claude Code

设置完成后，该项目中的每个 Claude Code 会话都会被自动追踪。会话结束时，追踪数据将导出到 MLflow。

MLflow Python SDK

如果您已经安装了配备 MLflow 的 Python 环境，也可以通过 MLflow CLI 配置追踪。

要求

• MLflow >= 3.4 (pip install 'mlflow>=3.4')
• 已安装并配置 Claude Code CLI

基本设置

bash

# Set up tracing in current directory
mlflow autolog claude

# Set up tracing in a specific directory
mlflow autolog claude -d ~/my-project

# Check tracing status
mlflow autolog claude --status

# Disable tracing
mlflow autolog claude --disable

配置示例

bash

# Set up with custom tracking URI
mlflow autolog claude -u file://./custom-mlruns
mlflow autolog claude -u sqlite:///mlflow.db

# Set up with Databricks backend and a specific experiment ID
mlflow autolog claude -u databricks -e 123456789

# Set up with a specific experiment name
mlflow autolog claude -n "My AI Project"

工作原理

1. 设置：mlflow autolog claude 会将 Claude Code 钩子写入项目目录下的 .claude/settings.json。
2. 自动追踪：当您在已配置的目录中运行 claude 时，会话会被自动追踪。
3. 查看结果：启动 mlflow server（或指向现有的后端）并打开 MLflow UI。

基础示例

bash

# Set up tracing in your project
mlflow autolog claude -d ~/my-project

# Navigate to the project directory
cd ~/my-project

# Use Claude Code normally - tracing happens automatically
claude "help me refactor this Python function to be more efficient"

# View traces in the MLflow UI
mlflow server

追踪 Token 使用量和成本

MLflow 无需额外设置即可自动跟踪 Claude Code 会话的 token 使用量和成本。每次 LLM 调用的 token 计数会记录在相关的 span 上，聚合后的成本和时间趋势会显示在内置的实验仪表板中。

有关以编程方式访问此信息的详情，请参阅 Token 使用量和成本跟踪。

故障排除

追踪未生效

• 确认插件已安装 (claude plugin list)，或者 mlflow autolog claude --status 显示追踪已启用。
• 安装插件后重启 Claude Code 以便加载。
• 验证您的机器是否可以访问跟踪 URI。
• 检查是否写入了正确的设置文件：./.claude/settings.json（项目作用域）或 ~/.claude/settings.json（用户作用域）。

追踪丢失

• Claude Code 的追踪数据在会话结束时导出，因此只有在退出会话后，它们才会出现在 MLflow 中。
• 检查 shell 级别的 MLFLOW_* 环境变量是否覆盖了您的项目或用户设置。
• 验证配置的实验是否存在，且解析出的实验 ID 是否有效。
• 对于 MLflow Python SDK 设置，请查看 .claude/mlflow/claude_tracing.log 中的日志。

禁用追踪

• 插件：claude plugin uninstall mlflow-tracing@mlflow-plugins（或 claude plugin disable ...）。
• MLflow Python SDK：mlflow autolog claude --disable。
• 运行时覆盖：在启动 claude 的环境中设置 MLFLOW_CLAUDE_TRACING_ENABLED=false。