クロード・コードの追跡

MLflow Tracing は、 Claude Agent SDK を使用して作成された Claude Code の会話とエージェントを自動的にトレースし、ユーザー プロンプト、AI 応答、ツールの使用状況、タイミング、セッション メタデータをキャプチャします。

MLflow は、Claude Code トレースの 2 つのアプローチをサポートしています。

• CLI トレース : MLflow CLI を介してトレースを構成して、対話型 Claude Code セッションを自動的にトレースします (MLflow 3.4 以降)
• SDK トレース : Claude Agent SDK (MLflow 3.5+) を使用して、Python アプリケーションのトレースをプログラムで有効にします。

要件

CLI tracing

Claude Code CLI トレースには以下が必要です。

• クロード・コード CLI
• MLflow 3.4 以降（Databricks 追加機能付き）

Bash

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

SDK tracing

Claude Agent SDK トレースには以下が必要です:

• クロード エージェント SDK 0.1.0またはそれ以降
• MLflow 3.5 以降（Databricks 追加機能付き）

Bash

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

Databricks環境変数を設定する

次の 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"

本番運用環境の場合は、安全なAPIキー管理のためにMosaic AI GatewayまたはDatabricksシークレットを使用します。

トレース・クロード

CLI または Claude Agent SDK を使用して Claude コードをトレースします。

CLI tracing

1. プロジェクト ディレクトリ内の.claude/settings.jsonファイルで Claude Code フックを構成するには、 mlflow autolog claudeを使用します。

   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

   追加の構成オプション:

   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

注記

トレースを無効にするには、 mlflow autolog claude --disableを実行します。これにより、 .claude/settings.jsonからトレース構成が削除されます。

2. 追跡状況を確認する

   Bash

   mlflow autolog claude --status

3. トレースを有効にしたプロジェクト ディレクトリで claude コマンドを使用すると、会話が自動的にトレースされます。

   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. MLflow UI でトレースを表示します。

   Bash

   # View traces in MLflow UI
   mlflow ui

SDK tracing

注記

MLflow はqueryへの直接呼び出しのトレースをサポートしていません。MLflow は、 ClaudeSDKClient使用するトレース インタラクションのみをサポートします。

Claude Agent SDK の自動ログ記録を有効にして、すべての Claude Agent SDK のインタラクションを追跡します。

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

MLflow の GenAI 評価フレームワークで SDK トレースを使用することもできます。

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

トラブルシューティング

CLI tracing

プロジェクトで CLI トレースが有効になっていることを確認します。

Bash

mlflow autolog claude --status

これには、現在のトレース構成と、それが Claude Code CLI に対してアクティブかどうかが表示されます。

トレースが機能しない:

• 設定されたディレクトリにいることを確認してください
• 確認する .claude/settings.json exists
• ログインを確認する .claude/mlflow/claude_tracing.log

失われた痕跡:

• 設定にMLFLOW_CLAUDE_TRACING_ENABLED=trueが含まれているか確認してください
• トラッキングURIにアクセスできることを確認する
• .claude/mlflow/claude_tracing.log のログを確認します。

SDK tracing

失われた痕跡:

• ClaudeSDKClientを作成する前にmlflow.anthropic.autolog()が呼び出されていることを確認します
• トラッキング URI とエクスペリメント ID が正しく構成されていることを確認してください