跟踪 Claude Code

MLflow Tracing 为 Claude Code 提供自动跟踪功能。

1. CLI 跟踪：自动跟踪交互式 Claude Code CLI 对话。
2. SDK 跟踪：跟踪 Python 应用程序中的 Claude Agent SDK 用法。

设置自动跟踪后，MLflow 将自动捕获 Claude Code 对话的跟踪记录，并将其记录到活动的 MLflow 实验中。跟踪记录会自动捕获以下信息：

• 用户提示和助手响应
• 工具使用（文件操作、代码执行、网络搜索等）
• 对话时间和持续时间
• 工具执行结果
• 会话元数据，包括工作目录和用户

要求

• MLflow >= 3.4 (pip install mlflow>=3.4)
• 对于 CLI 跟踪：已安装并配置 Claude Code CLI
• 对于 SDK 跟踪：Claude Agent SDK >= 0.1.0 (pip install claude-agent-sdk >= 0.1.0)

设置

Claude Code 跟踪可以通过 CLI 命令（用于交互式使用）或 Python SDK 导入（用于编程使用）进行配置。

CLI 跟踪

CLI 跟踪设置

使用 CLI 跟踪自动捕获交互式 Claude Code CLI 对话。

基本设置

# Set up tracing in current directory
mlflow autolog claude

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

# Check tracing status
mlflow autolog claude --status

# Disable tracing
mlflow autolog claude --disable

配置示例

# 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 specific experiment
mlflow autolog claude -n "My AI Project"

工作原理

1. 设置阶段：mlflow autolog claude 命令会在项目目录中的 .claude/settings.json 文件中配置 Claude Code 钩子。
2. 自动跟踪：在配置的目录中使用 claude 命令时，对话会自动被跟踪。
3. 查看结果：使用 MLflow UI 探索您的跟踪记录。

基本示例

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

# Navigate to 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 MLflow UI
mlflow ui

SDK 跟踪

SDK 跟踪设置

在构建以编程方式使用 Claude Agent SDK 的应用程序时，使用 SDK 跟踪。

基本设置

import mlflow.anthropic

# Enable automatic tracing for Claude Agent SDK
mlflow.anthropic.autolog()

启用后，所有 Claude Agent SDK 交互都将被自动跟踪。

注意

只有 ClaudeSDKClient 支持跟踪。直接调用 query 不会被跟踪！

完整示例

import asyncio
import mlflow.anthropic
from claude_agent_sdk import ClaudeSDKClient

# Enable autologging
mlflow.anthropic.autolog()

# Optionally configure MLflow experiment
mlflow.set_experiment("my_claude_app")


async def main():
    async with ClaudeSDKClient() as client:
        await client.query("What is the capital of France?")

        async for message in client.receive_response():
            print(message)


if __name__ == "__main__":
    asyncio.run(main())

使用 MLflow GenAI 评估进行 Claude 跟踪

您还可以将 SDK 跟踪与 MLflow 的 GenAI 评估框架结合使用。

import asyncio
import pandas as pd
from claude_agent_sdk import ClaudeSDKClient

import mlflow.anthropic
from mlflow.genai import evaluate, scorer
from mlflow.genai.judges import make_judge

mlflow.anthropic.autolog()


async def run_agent(query: str) -> str:
    """Run Claude Agent SDK and return response"""
    async with ClaudeSDKClient() as client:
        await client.query(query)

        response_text = ""
        async for message in client.receive_response():
            response_text += str(message) + "\n\n"

        return response_text


def predict_fn(query: str) -> str:
    """Synchronous wrapper for evaluation"""
    return asyncio.run(run_agent(query))


relevance = make_judge(
    name="relevance",
    instructions=(
        "Evaluate if the response in {{ outputs }} is relevant to "
        "the question in {{ inputs }}. Return either 'pass' or 'fail'."
    ),
    model="openai:/gpt-4o",
)

# Create evaluation dataset
eval_data = pd.DataFrame(
    [
        {"inputs": {"query": "What is machine learning?"}},
        {"inputs": {"query": "Explain neural networks"}},
    ]
)

# Run evaluation with automatic tracing
mlflow.set_experiment("claude_evaluation")
evaluate(data=eval_data, predict_fn=predict_fn, scorers=[relevance])

故障排除

CLI 跟踪

检查 CLI 状态

mlflow autolog claude --status

这会显示：

• 跟踪是否已启用
• 当前跟踪 URI
• 配置的实验
• 任何配置问题

常见的 CLI 问题

跟踪不起作用

• 确保您在已配置的目录中。
• 检查 .claude/settings.json 是否存在。
• 查看 .claude/mlflow/claude_tracing.log 中的日志。

缺少跟踪记录

• 检查您的配置中是否设置了 MLFLOW_CLAUDE_TRACING_ENABLED=true。
• 验证跟踪 URI 是否可访问。
• 查看 .claude/mlflow/claude_tracing.log 中的日志。

禁用 CLI 跟踪

要停止自动 CLI 跟踪，请执行以下操作：

mlflow autolog claude --disable

这将从 .claude/settings.json 中移除钩子，但会保留现有的跟踪记录。

SDK 跟踪

常见的 SDK 问题

没有出现跟踪记录

• 跟踪仅适用于 ClaudeSDKClient - 不支持直接使用 query()。
• 验证是否在创建 ClaudeSDKClient 之前调用了 mlflow.anthropic.autolog()。
• 检查跟踪 URI 和实验 ID 是否已正确配置。

禁用 SDK 跟踪

要禁用 SDK 跟踪，请执行以下操作：

mlflow.anthropic.autolog(disable=True)