Tracing Claude Code

MLflow Tracing automatically traces Claude Code conversations and agents authored using Claude Agent SDK, capturing user prompts, AI responses, tool usage, timing, and session metadata.

MLflow supports two approaches for Claude Code tracing:

• CLI tracing: Configure tracing through the MLflow CLI to automatically trace interactive Claude Code sessions (MLflow 3.4+)
• SDK tracing: Enable tracing programmatically for Python applications using the Claude Agent SDK (MLflow 3.5+)

Requirements

CLI tracing

Claude Code CLI tracing requires:

• Claude Code CLI
• MLflow 3.4 or later with Databricks extras

Bash

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

SDK tracing

Claude Agent SDK tracing requires:

• Claude Agent SDK 0.1.0 or later
• MLflow 3.5 or later with Databricks extras

Bash

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

Set Databricks environment variables

Configure the following Databricks environment variables:

Bash

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

For production environments, use Mosaic AI Gateway or Databricks secrets for secure API key management.

Trace Claude

Trace Claude Code using the CLI or Claude Agent SDK.

CLI tracing

1. Use mlflow autolog claude to configure Claude Code hooks in a .claude/settings.json file in your project directory:

   Bash

   # Set up tracing with Databricks (uses environment variables set earlier)
   mlflow autolog claude ~/my-project
   
   # Or set up tracing in current directory
   mlflow autolog claude

   Additional configuration options:

   Bash

   # 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

   note

   To disable tracing, run mlflow autolog claude --disable. This removes the tracing configuration from .claude/settings.json.

2. Check tracing status

   Bash

   mlflow autolog claude --status

3. When you use the claude command in your project directory with tracing enabled, your conversations are automatically traced:

   Bash

   # 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"
   

4. View traces in the MLflow UI:

   Bash

   # View traces in MLflow UI
   mlflow ui

SDK tracing

note

MLflow does not support tracing direct calls to query. MLflow only supports tracing interactions that use ClaudeSDKClient.

Enable autologging for Claude Agent SDK to trace all Claude Agent SDK interactions:

Python

import asyncio
import mlflow.anthropic
from claude_agent_sdk import ClaudeSDKClient

# Enable autologging
mlflow.anthropic.autolog()

# Disable autologging
# mlflow.anthropic.autolog(disable=True)

# 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())

You can also use SDK tracing with MLflow's GenAI evaluation framework:

Python

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

CLI tracing

Verify that CLI tracing is enabled for your project:

Bash

mlflow autolog claude --status

This displays the current tracing configuration and whether it's active for the Claude Code CLI.

Tracing not working:

• Ensure you're in the configured directory
• Check that .claude/settings.json exists
• Review logs in .claude/mlflow/claude_tracing.log

Missing traces:

• Check if MLFLOW_CLAUDE_TRACING_ENABLED=true in your configuration
• Verify the tracking URI is accessible
• Review logs in .claude/mlflow/claude_tracing.log

SDK tracing

Missing traces:

• Verify mlflow.anthropic.autolog() is called before creating the ClaudeSDKClient
• Check that the tracking URI and experiment ID are configured correctly