Claude Code ガイド

Appearance

Bash ツールサブプロセスへの W3C TRACEPARENT 環境変数の追加 ​

原文（日本語に翻訳） ​

OTEL トレーシングが有効な場合、Bash ツールのサブプロセスに W3C TRACEPARENT 環境変数を追加しました。これにより、子プロセスのスパンが Claude Code のトレースツリーに正しくペアレンティングされます。

原文（英語） ​

Added W3C TRACEPARENT env var to Bash tool subprocesses when OTEL tracing is enabled, so child-process spans correctly parent to Claude Code's trace tree

概要 ​

Claude Code v2.1.98 では、OpenTelemetry (OTEL) トレーシングが有効な環境において、Bash ツールが実行するサブプロセスに W3C TraceContext 仕様の TRACEPARENT 環境変数が自動的に設定されるようになりました。これにより、Claude Code が実行するシェルスクリプトやコマンドが独自のスパンを生成する場合、そのスパンが Claude Code の分散トレーシングツリーの正しい位置に配置されます。サービスの可観測性やデバッグ時に、Claude Code の操作と子プロセスの処理を一つのトレースとして関連付けて確認できるようになります。

基本的な使い方 ​

OTEL トレーシングを有効化した状態で Claude Code を使用すると、Bash ツールの実行時に TRACEPARENT が自動的にサブプロセスに伝播されます。

bash
# OTEL トレーシングを有効化（Jaeger などのバックエンドを使用する場合）
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
export OTEL_SERVICE_NAME="claude-code"

# Claude Code を起動
claude

# Bash ツールが実行されると、サブプロセスに自動的に
# TRACEPARENT が環境変数として渡される

TRACEPARENT の形式（W3C TraceContext 仕様）:

traceparent: 00-{trace-id}-{parent-id}-{flags}
例: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

実践例 ​

Jaeger を使ったトレーシングの可視化 ​

bash
# Docker で Jaeger を起動
docker run -d --name jaeger \
  -p 16686:16686 \
  -p 4317:4317 \
  jaegertracing/all-in-one:latest

# OTEL 設定を行う
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
export OTEL_SERVICE_NAME="claude-code"
export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"

# Claude Code を起動
claude

# Claude Code が Bash コマンドを実行すると、
# TRACEPARENT が自動的にサブプロセスに伝播される
# Jaeger UI (http://localhost:16686) でトレースを確認

OTEL 対応スクリプトとの連携 ​

TRACEPARENT を受け取り、独自のスパンを生成するスクリプトを作成することで、Claude Code のトレースツリーに統合できます。

bash
#!/bin/bash
# otel-aware-build.sh - TRACEPARENT を受け取る OTEL 対応ビルドスクリプト

# TRACEPARENT が設定されている場合、子スパンを作成
if [ -n "$TRACEPARENT" ]; then
  echo "OTEL トレーシング有効: $TRACEPARENT"
  # otel-cli などで子スパンを作成
  # otel-cli span \
  #   --name "build-step" \
  #   --tp-print \
  #   -- make build
fi

# 通常のビルド処理
make build

マイクロサービス環境での分散トレーシング ​

bash
# Claude Code から複数のサービスにまたがる操作を行う場合

# バックエンドサービスの設定（OTEL を受け付ける）
export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4317"

# Claude Code を起動
OTEL_SERVICE_NAME="claude-code" claude

# Claude Code がシェルスクリプト経由でサービスを呼び出す際、
# TRACEPARENT が自動的に伝播される
# これにより、Claude Code → スクリプト → サービスの
# 完全な呼び出しチェーンがトレースで可視化される

CI/CD パイプラインでのトレーシング統合 ​

yaml
# .github/workflows/claude-with-tracing.yml
name: Claude Code with OTEL Tracing
on: [push]

jobs:
  analyze:
    runs-on: ubuntu-latest
    env:
      OTEL_EXPORTER_OTLP_ENDPOINT: "https://your-otel-backend.example.com"
      OTEL_SERVICE_NAME: "claude-code-ci"
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - name: Run Claude Code Analysis
        run: |
          # TRACEPARENT が自動的に Bash サブプロセスに伝播される
          claude --print "このプロジェクトのコードを分析してください"

注意点 ​

  • TRACEPARENT の自動伝播は OTEL トレーシングが有効な場合のみ機能します（OTEL_EXPORTER_OTLP_ENDPOINT などの設定が必要）
  • TRACEPARENT の形式は W3C TraceContext 仕様 に準拠しています
  • サブプロセスが TRACEPARENT を活用するには、そのプロセス自体が OTEL に対応している必要があります
  • TRACEPARENT を受け取るだけでは子スパンは生成されません。スクリプト内で otel-cli などのツールを使って明示的にスパンを作成する必要があります
  • この機能は Claude Code v2.1.98 以降で利用可能です
  • OTEL バックエンドの設定（Jaeger、Zipkin、Grafana Tempo など）は別途必要です

関連情報 ​