BETA_TRACING_ENDPOINTでdetailed beta tracingの送信先を変える

BETA_TRACING_ENDPOINTとは何か

BETA_TRACING_ENDPOINT は、Claude Codeの「detailed beta tracing(詳細ベータトレーシング)」が出力するログとトレースの送信先を指定するOTLPエンドポイントです。ENABLE_BETA_TRACING_DETAILED=1 とセットで設定すると、通常のOTLPエクスポーター設定を経由せず、ログとトレースがこのエンドポイントに直接送られます。

この2変数は、Claude Codeが通常提供しているOpenTelemetry連携とは別枠の機能です。通常のOTEL_EXPORTER_OTLP_ENDPOINTがメトリクス・ログ・トレースの標準的な送信先を決めるのに対し、BETA_TRACING_ENDPOINTはdetailed beta tracingが有効なときだけ働き、ログとトレースをそちらへ横取りします。メトリクスの送信先には影響しません。

有効化に必要な2つの変数と設定できる場所

detailed beta tracingを有効にするには、次の2変数を両方設定します。

export ENABLE_BETA_TRACING_DETAILED=1
export BETA_TRACING_ENDPOINT=http://collector.example.com:4317
claude

設定できる場所はシェル環境変数、ユーザー設定、管理設定(managed settings)の3つに限られます。プロジェクト設定・ローカル設定からは無効です。公式ドキュメントは、セッションの内容そのものをエクスポートする変数(この2つとOTEL_LOG_RAW_API_BODIES)をプロジェクト・ローカル設定の対象外に分類しており、チェックアウトしたリポジトリ側の設定ファイルがセッション内容の送信先を勝手に決められないようにする狙いです。

インタラクティブなCLIセッションでは、これに加えて組織がこのベータ機能のallowlistに登録されていることも条件になります。Agent SDKや-pを付けた非対話セッションはallowlist登録を必要としません。

有効化すると何が変わるか

detailed beta tracingをオンにすると、通常のトレーシングでは出ない2種類の情報が追加されます。

1. claude_code.hook スパン

Hookの実行を表すスパンで、hook_event(PreToolUseなど)、hook_name、実行されたhookコマンド数(num_hooks)、成功数・ブロック数・失敗数・キャンセル数を属性として持ちます。このスパンはdetailed beta tracingが有効なときにしか現れません。CLAUDE_CODE_ENHANCED_TELEMETRY_BETAだけを設定してトレーシング自体を有効にしていても、hookスパンは生成されません。

2. content-bearing(内容を含む)なスパン属性

new_context、system_prompt_preview、user_system_prompt、tool_input、response.model_outputといった属性が追加されます。これらはモデルの応答内容やツールの入出力、システムプロンプトそのものを含み得るため、安定したスパンスキーマの一部ではないと明記されています。実際に出力されるかどうかはさらに個別のゲートに依存し、たとえばclaude_code.toolスパンのnew_contextはツール呼び出しの結果を運びますが、OTEL_LOG_TOOL_CONTENT=1も別途必要です。claude_code.interactionスパンやclaude_code.llm_requestスパンのnew_contextはユーザープロンプトを運び、OTEL_LOG_USER_PROMPTS=1が条件になります。

スパンの階層とhookスパンの位置

Claude Codeのトレースは、ユーザーの1プロンプトごとにclaude_code.interactionというルートスパンから始まります。その配下にAPI呼び出し・ツール実行・hook実行が子スパンとして並び、ツールスパンはさらに権限判断待ちの時間と実行本体の2つの子スパンを持ちます。

claude_code.interaction
├── claude_code.llm_request
├── claude_code.tool
│   ├── claude_code.tool.blocked_on_user
│   └── claude_code.tool.execution
├── claude_code.hook                    (detailed beta tracingが必要)
└── (Agentツールでサブエージェントを起動した場合) 子のllm_request / toolスパン

claude_code.hookスパンだけがdetailed beta tracing専用で、通常のトレーシングを有効にしただけでは現れません。hook_definitions(hook設定のJSONシリアライズ)属性はさらにOTEL_LOG_TOOL_DETAILS=1のゲートが掛かっており、detailed beta tracingと両方を有効にして初めて出力されます。

PreToolUsehookがツール呼び出しを遅延させた場合、Claude Codeはその時点のトレースコンテキストを保存し、セッションを再開してツールが実際に実行されたときに、遅延を発生させたターンのclaude_code.interactionスパンの子として合流させます。

サブプロセスへのトレースコンテキスト伝播

トレーシングが有効な状態では、BashやPowerShellのサブプロセスにTRACEPARENT環境変数が自動的に渡されます。これは実行中のツール実行スパンのW3Cトレースコンテキストで、TRACEPARENTを読み取るスクリプトやツールがあれば、その処理を同じトレースの子スパンとして紐付けられます。

Claude CodeがAnthropicのAPIに直接接続している場合、モデルへのリクエストにはclaude_code.llm_requestスパンのコンテキストを載せたtraceparentヘッダーが付き、APIからのtraceresponseヘッダーはスパンリンクとして記録されます。Agent SDKや-p付きの非対話セッションでは、逆に呼び出し元のTRACEPARENT/TRACESTATEを読み取り、Claude Code側のスパンを呼び出し元の分散トレースの子として表示できます。対話セッションはCIやコンテナ環境の値を誤って引き継がないよう、外部からのTRACEPARENTを無視します。

query_sourceとquery_source_safeの違い

claude_code.llm_requestスパンには、どのサブシステムがそのリクエストを発行したかを示す属性が2種類あります。query_sourceはrepl_main_threadやサブエージェント名をそのまま記録する詳細な値で、ENABLE_BETA_TRACING_DETAILEDが有効なときだけ出力されます。一方query_source_safeは:を.に置き換え、ユーザー定義のカスタムエージェント名をagent.customに丸めた安全な形で、detailed beta tracingの有無にかかわらず常に出力されます。詳細なサブエージェント名まで追いたいだけなら、detailed beta tracing全体を有効にせずともquery_source_safeで足りる場合があります。

通常のTraces(beta)機能との違い

Claude Codeには、CLAUDE_CODE_ENHANCED_TELEMETRY_BETAとOTEL_TRACES_EXPORTERで有効にする通常のトレーシング機能(Traces beta)がすでにあります。これはCLAUDE_CODE_ENABLE_TELEMETRY=1と組み合わせて使う、OpenTelemetryの標準的なトレースエクスポート機能です。

detailed beta tracingはこの上位に乗る別レイヤーで、次の点が異なります。

両者は独立に有効化できますが、claude_code.hookスパンと内容付き属性を得たいなら、通常のTraces(beta)の設定だけでは足りず、detailed beta tracingの2変数を追加で設定する必要があります。

管理設定(managed settings)がある環境での注意

管理設定側でOTEL_EXPORTER_OTLP_ENDPOINTのようなログ・トレースの送信先やヘッダー、プロトコルを指定すると、Claude Codeは開発者側が設定したBETA_TRACING_ENDPOINTを起動時に取り除きます。管理設定がメトリクス専用のエンドポイントや認証情報しか指定していない場合は、BETA_TRACING_ENDPOINTは削除されません。

この挙動には過去にバグがありました。v2.1.251より前のバージョンでは、開発者が設定したBETA_TRACING_ENDPOINTが、管理設定側で固定したはずのコレクター指定を素通りしてログとトレースをリダイレクトしてしまう不具合がありました。v2.1.251でこの問題と、プロジェクト設定側からdetailed beta tracingや生APIボディのログ出力を有効化できてしまう不具合が合わせて修正されています。管理設定でOTLPの送信先を固定している組織は、Claude Codeをこのバージョン以降に保つ必要があります。

管理設定で組織全体に配布する

管理設定(managed settings)からenvブロックでこの2変数を配ると、開発者のシェル設定やユーザー設定より優先されます。

{
  "env": {
    "ENABLE_BETA_TRACING_DETAILED": "1",
    "BETA_TRACING_ENDPOINT": "http://collector.example.com:4317"
  }
}

同じ変数がシェルと設定ファイルの両方にある場合は設定ファイル側が勝ちます。設定ファイル同士では管理設定がユーザー設定・プロジェクト設定より優先されるという通常の優先順位がそのまま適用され、プロジェクト・ローカル設定はそもそもこの2変数を書けないため優先順位を争う対象になりません。

よくあるつまずき

• ENABLE_BETA_TRACING_DETAILEDだけ設定してBETA_TRACING_ENDPOINTを忘れる — claude_code.hookスパンも内容付き属性も出力されません。2変数は必ず組で設定します
• プロジェクトの.claude/settings.jsonに書いて配布しようとする — Claude Codeは起動時にこの2変数を無視し、claude --debugで警告ログが出ます。チーム展開はシェル・ユーザー設定・管理設定のいずれかで行います
• CLAUDE_CODE_ENHANCED_TELEMETRY_BETAだけでclaude_code.hookスパンが出ると思い込む — 通常のTraces(beta)を有効にしただけではhookスパンは生成されません
• allowlist登録前にインタラクティブセッションで試して何も出ないと勘違いする — Agent SDKや-pセッションでは登録不要なので、まずそちらで動作を確認すると切り分けやすくなります
• 管理設定でOTLP収集先を固定している組織で古いバージョンのまま使う — v2.1.251より前はBETA_TRACING_ENDPOINTが管理設定の固定を素通りする不具合があったため、該当バージョン以降に更新してから運用します

使うべきかの判断

detailed beta tracingは、モデル応答やツール出力、システムプロンプトといった内容を伴う情報をトレーシングバックエンドへ送る機能です。有効化する前に、送信先のコレクターやその後段のログ基盤がどこまでアクセス制御されているかを確認しておくのが安全です。

まとめ

BETA_TRACING_ENDPOINTとENABLE_BETA_TRACING_DETAILEDは、必ず2つ組で設定する専用ペアです。設定できる場所はシェル・ユーザー設定・管理設定に限られ、プロジェクト設定やローカル設定からは効きません。有効化するとclaude_code.hookスパンと内容付きの属性が追加され、Hookの実行状況やプロンプト・ツール出力までトレースに残せるようになります。ただしインタラクティブCLIセッションでは組織のallowlist登録が前提で、管理設定でOTLP送信先を固定している環境ではv2.1.251以降を使う必要があります。すでにHooksをHTTPエンドポイントで受ける構成を組んでいるなら、hookの成否をスパン単位でも追える点は組み合わせる価値があります。