Rastreando o código de Claude

MLflow Tracing rastreia automaticamente conversas e agentes do Claude Code criados com o Claude Agent SDK, capturando prompts do usuário, respostas AI , uso de ferramentas, tempo e metadados da sessão.

O MLflow suporta duas abordagens para o rastreamento do Código Claude:

• Rastreamento via CLI : Configure o rastreamento através da CLI do MLflow para rastrear automaticamente sessões interativas do Claude Code (MLflow 3.4+).
• Rastreamento do SDK : Habilite o rastreamento programaticamente para aplicativos Python usando o SDK do Agente Claude (MLflow 3.5+).

Requisitos

CLI tracing

O rastreamento da CLI do Claude Code requer:

• CLI do Claude Code
• MLflow 3.4 ou posterior com extras do Databricks

Bash

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

SDK tracing

O rastreamento do SDK do Agente Claude requer:

• SDK do Agente Claude 0.1.0 ou mais tarde
• MLflow 3.5 ou posterior com extras do Databricks

Bash

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

Definir variável de ambiente Databricks

Configure a seguinte variável de ambiente Databricks :

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"

Para ambientes de produção, utilize Mosaic AI Gateway ou os segredos Databricks para um gerenciamento seguro key API .

Trace Claude

Rastreie o código Claude usando a CLI ou o SDK do Agente Claude.

CLI tracing

1. Use mlflow autolog claude para configurar os hooks do Claude Code em um arquivo .claude/settings.json no diretório do seu projeto:

   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

   Opções de configuração adicionais:

   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

nota

Para desativar o rastreio, execute mlflow autolog claude --disable. Isso remove a configuração de rastreamento de .claude/settings.json.

2. Verificar status de rastreamento

   Bash

   mlflow autolog claude --status

3. Ao usar o comando claude no diretório do seu projeto com o rastreamento ativado, suas conversas são rastreadas automaticamente:

   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. Visualizar rastreamentos na interface do usuário MLflow :

   Bash

   # View traces in MLflow UI
   mlflow ui

SDK tracing

nota

O MLflow não suporta o rastreamento de chamadas diretas para query. O MLflow suporta apenas o rastreamento de interações que usam ClaudeSDKClient.

Ative o registro automático para o SDK do Agente Claude para rastrear todas as interações do SDK do Agente Claude:

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

Você também pode usar o rastreamento do SDK com a estrutura de avaliação GenAI do MLflow:

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])

Solução de problemas

CLI tracing

Verifique se o rastreamento da CLI está ativado para o seu projeto:

Bash

mlflow autolog claude --status

Esta opção exibe a configuração de rastreamento atual e se ela está ativa para a CLI do Claude Code.

O rastreamento não está funcionando:

• Certifique-se de estar no diretório configurado.
• Verifique isso .claude/settings.json exists
• Revisar login .claude/mlflow/claude_tracing.log

Vestígios desaparecidos:

• Verifique se MLFLOW_CLAUDE_TRACING_ENABLED=true está na sua configuração.
• Verifique se o URI de acompanhamento está acessível.
• Analise o log em .claude/mlflow/ log

SDK tracing

Vestígios desaparecidos:

• Verifique se mlflow.anthropic.autolog() foi chamado antes de criar o ClaudeSDKClient.
• Verifique se o URI de acompanhamento e o ID do experimento estão configurados corretamente.