Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

SDK/ヘッドレスセッションが環境変数から TRACEPARENT/TRACESTATE を読み取り、分散トレースリンクに対応するようになった

原文（英語） ​

SDK/headless sessions now read TRACEPARENT/TRACESTATE from the environment for distributed trace linking

概要 ​

Claude Code の SDK およびヘッドレスセッションが、W3C Trace Context 標準の TRACEPARENT および TRACESTATE 環境変数を読み取り、既存の分散トレーシングシステムと連携できるようになりました。これにより、Claude Code を組み込んだ CI/CD パイプラインやマイクロサービスシステムにおいて、エンドツーエンドのトレース追跡が可能になります。

基本的な使い方 ​

bash
# 既存のトレーシングコンテキストを Claude Code セッションに引き継ぐ
export TRACEPARENT="00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
export TRACESTATE="vendor1=opaquevalue1"

# ヘッドレスセッションを実行（トレースコンテキストが自動的に引き継がれる）
claude --headless "コードを分析してレポートを作成して"

実践例 ​

CI/CD パイプラインへの統合 ​

GitHub Actions などの CI 環境で既存のトレースと Claude Code を連携：

yaml
# .github/workflows/ci.yml
jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - name: Generate trace context
        run: |
          # トレースIDを生成（OpenTelemetry SDK などで生成することも可能）
          TRACE_ID=$(openssl rand -hex 16)
          SPAN_ID=$(openssl rand -hex 8)
          echo "TRACEPARENT=00-${TRACE_ID}-${SPAN_ID}-01" >> $GITHUB_ENV

      - name: Run Claude Code analysis
        env:
          TRACEPARENT: ${{ env.TRACEPARENT }}
        run: |
          claude --headless "コードの品質チェックを実行して結果を返して"

OpenTelemetry との連携 ​

OpenTelemetry で計装されたアプリケーションから Claude Code を呼び出す：

python
from opentelemetry import trace
from opentelemetry.propagate import inject
import subprocess
import os

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("claude-code-analysis"):
    # 現在のトレースコンテキストを環境変数として設定
    env = os.environ.copy()
    carrier = {}
    inject(carrier)
    
    # TRACEPARENT, TRACESTATE を環境変数に追加
    if "traceparent" in carrier:
        env["TRACEPARENT"] = carrier["traceparent"]
    if "tracestate" in carrier:
        env["TRACESTATE"] = carrier["tracestate"]
    
    # Claude Code をヘッドレスで実行
    result = subprocess.run(
        ["claude", "--headless", "コードをレビューして"],
        env=env,
        capture_output=True,
        text=True
    )

Claude Code テレメトリの設定（完全な分散トレーシング） ​

Claude Code 側でもテレメトリを有効化することで、完全なトレースチェーンを構築：

bash
# Claude Code のテレメトリを有効化
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# OpenTelemetry エクスポーター設定
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# 外部トレースコンテキストを設定
export TRACEPARENT="00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"

# ヘッドレスセッション実行
claude --headless "タスクを実行して"

TRACEPARENT フォーマット ​

00-TRACEID-SPANID-FLAGS

例: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
    ^  ^                                ^                ^
    |  |-- 128ビットトレースID           |-- 64ビット      |-- フラグ
    |      (32 文字の16進数)             スパンID          (01=サンプリング)
    バージョン(00)

注意点 ​

  • この機能は SDK/ヘッドレスセッション専用です。インタラクティブな CLI セッションには影響しません
  • TRACEPARENT の形式は W3C Trace Context 仕様（v1）に準拠する必要があります
  • 完全な分散トレーシングを利用するには、Claude Code 側のテレメトリも有効化が必要です
  • TRACESTATE はベンダー固有の追加情報を含めるためのオプションフィールドです

関連情報 ​