跟踪 Claude 代码

MLflow 跟踪会自动跟踪使用 Claude 代理 SDK 创作的 Claude Code 对话和代理，捕获用户提示、AI 响应、工具使用情况、计时和会话元数据。

MLflow 支持用于 Claude Code 跟踪的两种方法：

CLI 跟踪：通过 MLflow CLI 配置跟踪以自动跟踪交互式 Claude Code 会话（MLflow 3.4+）
SDK 跟踪：使用 Claude 代理 SDK 以编程方式为 Python 应用程序启用跟踪（MLflow 3.5+）

要求

SDK 追踪

Claude Agent SDK 跟踪要求：

Claude 代理 SDK 0.1.0 或更高版本
使用 Databricks Extras 的 MLflow 3.5 或更新版本

pip install --upgrade "mlflow[databricks]>=3.5" "claude-agent>=0.1.0"

CLI 跟踪

Claude Code CLI 跟踪需要以下条件：

Claude CLI
MLflow 3.4 或更高版本，附带 Databricks 附加功能

pip install --upgrade "mlflow[databricks]>=3.4"

将 “Claude Code” 追踪至 Databricks

SDK 追踪

设置 Databricks 和 Anthropic 的环境变量：

export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"
export DATABRICKS_TOKEN="your-personal-access-token"
export ANTHROPIC_API_KEY="your-anthropic-api-key"

对于生产环境，请使用马赛克 AI 网关或 Databricks 机密进行安全 API 密钥管理。

为 Claude 代理 SDK 启用自动记录以跟踪所有 Claude 代理 SDK 交互：

注释

MLflow 不支持跟踪对 query 的直接调用。 MLflow 仅支持跟踪使用 ClaudeSDKClient 的交互。

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.anthropic.autolog(disable=True)。

在 Databricks 工作区的 MLflow 实验 UI 中查看跟踪数据。

CLI 跟踪

配置 Claude Code 挂钩。在项目目录中的 mlflow autolog claude 文件中使用 .claude/settings.json 配置挂钩：

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

# Or set up tracing in current directory
mlflow autolog claude

其他配置选项：

# Specify experiment by name
mlflow autolog claude -n "My AI Project"

# Specify experiment by ID
mlflow autolog claude -e 123456789

# Use local file-based tracking instead of Databricks
mlflow autolog claude -u file://./custom-mlruns
mlflow autolog claude -u sqlite:///mlflow.db

注释

若要禁用跟踪，请运行 mlflow autolog claude --disable。这会从 .claude/settings.json中删除跟踪配置。

添加 Databricks 环境变量。通过 mlflow autolog claude 创建的挂钩在其自身环境中运行，并不继承 Shell 环境变量。若要追踪 Databricks，请将所需的环境变量添加到env中每个.claude/settings.json挂钩的节中。

{
  "hooks": {
    "ConversationStart": [
      {
        "type": "command",
        "command": "python -m mlflow.anthropic.autolog.claude.init_span",
        "timeout": 30000,
        "env": {
          "MLFLOW_CLAUDE_TRACING_ENABLED": "true",
          "MLFLOW_TRACKING_URI": "databricks",
          "DATABRICKS_HOST": "https://your-workspace.cloud.databricks.com",
          "DATABRICKS_TOKEN": "your-databricks-token"
        }
      }
    ],
    "ConversationTurn": [
      {
        "type": "command",
        "command": "python -m mlflow.anthropic.autolog.claude.end_span",
        "timeout": 30000,
        "env": {
          "MLFLOW_CLAUDE_TRACING_ENABLED": "true",
          "MLFLOW_TRACKING_URI": "databricks",
          "DATABRICKS_HOST": "https://your-workspace.cloud.databricks.com",
          "DATABRICKS_TOKEN": "your-databricks-token"
        }
      }
    ],
    "Stop": [
      {
        "type": "command",
        "command": "python -m mlflow.anthropic.autolog.claude.end_span --end-trace",
        "timeout": 30000,
        "env": {
          "MLFLOW_CLAUDE_TRACING_ENABLED": "true",
          "MLFLOW_TRACKING_URI": "databricks",
          "DATABRICKS_HOST": "https://your-workspace.cloud.databricks.com",
          "DATABRICKS_TOKEN": "your-databricks-token"
        }
      }
    ]
  }
}

将 your-workspace.cloud.databricks.com 替换为您的 Databricks 工作区 URL，将your-databricks-token 替换为您的个人访问令牌。

若要指定要使用的 MLflow 试验，请将 MLFLOW_EXPERIMENT_NAME 或 MLFLOW_EXPERIMENT_ID 添加到每个 hook 的 env 部分。

"env": {
  "MLFLOW_CLAUDE_TRACING_ENABLED": "true",
  "MLFLOW_TRACKING_URI": "databricks",
  "DATABRICKS_HOST": "https://your-workspace.cloud.databricks.com",
  "DATABRICKS_TOKEN": "your-databricks-token",
  "MLFLOW_EXPERIMENT_NAME": "/Users/your-email@company.com/my-claude-traces"
}

转到项目目录，并正常使用 Claude Code。对话会自动记录至 Databricks：
```
cd ~/my-project
claude "help me refactor this Python function to be more efficient"
```
在 Databricks 工作区的 MLflow 实验 UI 中查看跟踪数据。

高级：使用评估进行 SDK 跟踪

可以将 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])

Troubleshooting

SDK 追踪

缺少痕迹：

在创建mlflow.anthropic.autolog()之前，需先调用验证ClaudeSDKClient。
检查是否正确设置了环境变量（DATABRICKS_HOST， DATABRICKS_TOKEN）
验证 Databricks 令牌是否已过期

CLI 跟踪

请验证项目是否已启用 CLI 追踪功能：

mlflow autolog claude --status

这会显示当前跟踪配置，以及它是否对 Claude Code CLI 处于活动状态。

跟踪不起作用：

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

缺少痕迹：

检查配置中是否存在MLFLOW_CLAUDE_TRACING_ENABLED=true
验证跟踪 URI 是否可访问
在 .claude/mlflow/claude_tracing.log 查看日志

Databricks 连接问题：

验证 MLFLOW_TRACKING_URI、DATABRICKS_HOST和DATABRICKS_TOKEN在env节中是否设置在每个挂钩.claude/settings.json
Shell 环境变量不会传递给 Claude Code 钩子，变量必须在设置文件中。
检查您的 Databricks 令牌是否已失效
验证工作区 URL 是否正确（例如 https://your-workspace.cloud.databricks.com）

Last updated on 2026-03-13

跟踪 Claude 代码

要求

SDK 追踪

CLI 跟踪

将 “Claude Code” 追踪至 Databricks

SDK 追踪

CLI 跟踪

高级：使用评估进行 SDK 跟踪

Troubleshooting

SDK 追踪

CLI 跟踪

其他资源