Claude Code ガイド

Appearance

OTELトレーシングの並行SDKコールとヘッドレスターン対応改善 ​

原文（日本語に翻訳） ​

OTEL トレーシングを改善しました。インタラクションスパンが並行 SDK コール下でフルターンを正しくラップするようになり、ヘッドレスターンはターンごとにスパンを終了するようになりました。

原文（英語） ​

Improved OTEL tracing: interaction spans now correctly wrap full turns under concurrent SDK calls, and headless turns end spans per-turn

概要 ​

OpenTelemetry（OTEL）トレーシングの精度が向上しました。これまで並行して複数の SDK コールが行われる場合、インタラクションスパンが正しいターンの境界でラップされないことがありました。また、ヘッドレスモードでのターンに対するスパンの終了タイミングも修正されました。これにより、分散トレーシングシステムでの Claude Code の動作の可視性が向上します。

基本的な使い方 ​

OTEL トレーシングを有効にするには、環境変数を設定します。改善された動作は自動的に適用されます。

bash
# OTEL トレーシングの有効化
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
export OTEL_SERVICE_NAME="claude-code"

# Claude Code を起動
claude

トレーシングバックエンド（Jaeger、Zipkin、Grafana Tempo など）で正確なスパンデータを確認できます。

実践例 ​

並行SDK呼び出しのトレーシング精度向上 ​

複数のサブエージェントや並行タスクが実行される場合、各インタラクションスパンが正しいターン範囲をカバーするようになります。

bash
# OTEL エンドポイントの設定
export OTEL_EXPORTER_OTLP_ENDPOINT="http://jaeger:4318"
export OTEL_SERVICE_NAME="claude-code-dev"

# 並行エージェントタスクを実行
claude --headless "複数のファイルを並行して解析してください"

# Jaeger UI で確認すると:
# 改善前: 並行SDK呼び出しのスパンが重複したり、ターン境界が不正確
# 改善後: 各インタラクションスパンが正確にフルターンをカバー

ヘッドレスモードでのターンごとのスパン ​

ヘッドレスモード（--headless または --print）で使用する場合、各ターンのスパンが適切なタイミングで終了するようになります。

bash
# ヘッドレスモードでのバッチ処理
for file in *.py; do
  claude --print "このファイルをレビューしてください: $file" --input "$file"
done

# 各コマンドのスパンが独立して記録される:
# Span 1: "このファイルをレビュー... main.py" [開始 → 終了]
# Span 2: "このファイルをレビュー... utils.py" [開始 → 終了]
# ← 改善前: ヘッドレスターンのスパン終了タイミングが不正確

Grafana/Jaeger での可視化 ​

OTEL バックエンドと組み合わせて、Claude Code のパフォーマンス分析が正確に行えるようになります。

yaml
# docker-compose.yml の例（Jaeger + OTEL Collector）
services:
  jaeger:
    image: jaegertracing/all-in-one:latest
    ports:
      - "16686:16686"  # Jaeger UI
      - "4318:4318"    # OTLP HTTP
  
  claude-code:
    environment:
      OTEL_EXPORTER_OTLP_ENDPOINT: "http://jaeger:4318"
      OTEL_SERVICE_NAME: "claude-code"
bash
# 設定後にClaude Codeを起動
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
claude

# Jaeger UI (http://localhost:16686) で正確なスパンを確認

SDK 統合での並行処理監視 ​

Claude Code SDK を使ったアプリケーションで並行処理を行う場合、各インタラクションのトレースが正確に分離されます。

python
# SDK を使った並行処理の例
import asyncio
from anthropic import Anthropic

async def parallel_tasks():
    client = Anthropic()
    
    # 並行して複数のタスクを実行
    tasks = [
        client.messages.create(...),
        client.messages.create(...),
        client.messages.create(...),
    ]
    results = await asyncio.gather(*tasks)
    
    # 各タスクのスパンが正確にトレースされる
    # Jaeger で3つの独立したインタラクションスパンを確認可能

注意点 ​

  • OTEL トレーシングを使用するには、OTEL_EXPORTER_OTLP_ENDPOINT 環境変数の設定が必要です。
  • 並行 SDK 呼び出しのスパン改善は、複数のエージェントや並行タスクを使用している場合に特に効果があります。
  • ヘッドレスターンのスパン修正は --headless または --print モードで実行した場合に適用されます。
  • OTEL データはトレーシングバックエンドの容量設定に応じてサンプリングされる場合があります。

関連情報 ​