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が有効なときだけ働きます。公式の説明が置き換え対象にしているのはログとトレースの送信先で、メトリクスは含まれていません。

有効化の手順と設定できる場所

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

プロジェクト・ローカル設定が対象外なのは、セッションの内容そのものを外へ出す変数だからです。公式の設定リファレンスは、この2変数とOTEL_LOG_RAW_API_BODIESを「チェックアウトしたリポジトリに握らせない変数」に分類しています。OTEL_LOG_TOOL_DETAILSなどの内容系の変数も、project・local設定ではオフにする値(0)だけが有効です。

有効化すると何が追加されるか

通常のトレーシングでは出ない情報が2種類増えます。

claude_code.hookスパン

Hookの実行を表すスパンです。hook_event(PreToolUseなど)、hook_name(PreToolUse:Writeのような完全名)、実行されたhookコマンド数のnum_hooks、所要時間のduration_msを持ちます。成功・ブロック・ブロックしない失敗・キャンセルの件数も属性に入ります。

このスパンはdetailed beta tracingが有効なときにしか現れません。CLAUDE_CODE_ENHANCED_TELEMETRY_BETAだけでは生成されません。

内容を含むスパン属性

new_context、system_reminders、system_prompt_preview、user_system_prompt、tool_input、response.model_outputが追加されます。安定したスパンスキーマには含まれません。さらに属性ごとに別のゲート変数があり、2変数だけでは中身が空のままです。

OTEL_LOG_USER_PROMPTS=1を足すと、システムプロンプト全文を運ぶclaude_code.system_promptイベントも出ます。最初に新しいシステムプロンプトを送るときと、コンパクション後に出ます。内容の長さは既定で60 KBに切り詰められます。

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

Claude Codeのトレースは、ユーザーの1プロンプトごとにclaude_code.interactionというルートスパンから始まります。API呼び出し、ツール実行、hook実行がその子として並びます。

claude_code.interaction
├── claude_code.llm_request
├── claude_code.hook                    (detailed beta tracingが必要)
└── claude_code.tool
    ├── claude_code.tool.blocked_on_user
    ├── claude_code.tool.execution
    └── (Agentツール) サブエージェントのllm_request / toolスパン

サブエージェントのスパンは、親のclaude_code.toolスパンの下にぶら下がります。PreToolUsehookがツール呼び出しを遅延させた場合は、その時点のトレースコンテキストが保存されます。セッションを再開してツールが再実行されると、そのスパンは遅延したターンのclaude_code.interactionの子として合流します。

hook_definitions属性はOTEL_LOG_TOOL_DETAILS=1のゲートも受けます。hookスパンの設定内容まで見たいときは、この変数も要ります。

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

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

Claude CodeがAnthropicのAPIに直接接続している場合、モデルへのリクエストにはclaude_code.llm_requestスパンのコンテキストを載せたtraceparentヘッダーが付きます。APIからのtraceresponseヘッダーはスパンリンクとして記録されます。

ANTHROPIC_BASE_URLでプロキシを経由している場合、traceparentヘッダーとTRACEPARENT変数は既定では送られません。理由は、未知のヘッダーを拒否するプロキシがあるためです。プロキシ越しでも伝播させたいときは、CLAUDE_CODE_PROPAGATE_TRACEPARENT=1 を設定します。

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にまとめた形です。値の例はrepl_main_threadやagent.builtin.general-purposeで、detailed beta tracingの有無にかかわらず常に出ます。v2.1.268以降の属性です。

組み込みエージェントの種類を追うだけなら、detailed beta tracingを入れなくてもquery_source_safeで足ります。

通常のTraces(beta)とどう使い分けるか

通常のトレーシングは、CLAUDE_CODE_ENABLE_TELEMETRY=1、CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1、OTEL_TRACES_EXPORTERの3つで有効にします。detailed beta tracingは、通常のTracesとは別に、専用の2変数で有効にします。

hookスパンや内容付き属性が欲しいなら、通常のTraces(beta)の設定だけでは足りません。hookの成否だけ追うなら通常のTraces(beta)に2変数を足す形、プロンプトやツール出力まで追うならOTEL_LOG_*のゲート変数も足す形になります。

管理設定がある環境で何が起きるか

管理設定でログやトレースの送信先を固定している場合、開発者が設定したBETA_TRACING_ENDPOINTは起動時に取り除かれます。取り除かれる条件は、管理設定が次のいずれかでログまたはトレースの行き先を決めているときです。

• ログ・トレース用の汎用またはシグナル別のエンドポイントや認証情報
• otelHeadersHelper
• ログまたはトレースのエクスポーター指定がnone・console・空のとき
• CLAUDE_CODE_ENABLE_TELEMETRYのオフ

メトリクス専用のエンドポイントや認証情報だけなら、BETA_TRACING_ENDPOINTは残ります。管理設定でメトリクスだけ別の収集先に向けている組織では、開発者側のdetailed beta tracingがそのまま働きます。

管理設定でOTLPの送信先を固定している組織では、v2.1.251より前のバージョンが残っていないかが確認点です。

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

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

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

同じ変数がシェルと設定ファイルの両方にある場合は、設定ファイル側が勝ちます。設定ファイル同士では管理設定がユーザー設定より優先され、project・local設定はこの2変数を書けないので争いに加わりません。

Claude Desktopアプリやセルフホスト環境のランナーがセッションを起動する場合は例外です。起動環境が組み立てた値が優先され、すでに設定済みの変数について設定ファイルのenvは無視されます。無視された変数名はデバッグログに出ます。

効かないときの切り分け

設定したのに何も出ないときは、変数を捨てられているのか、条件が足りないのかで対処が分かれます。project・local設定で無視された変数の名前は、セッション内の/statusかclaude doctorで確かめられます。どちらも変数名だけを一覧し、値は表示しません。-pやAgent SDKでは起動時のnoticeが出ないので、コレクター側にデータが届いているかで確かめます。

Claude Desktopやセルフホストの起動環境に値を上書きされた場合は、無視された変数名がデバッグログに出ます。v2.1.289のclaude --helpには、デバッグ用に次の2つのオプションが載っています。

-d, --debug [filter]                  Enable debug mode with optional category
                                      filtering (e.g., "api,hooks" or
                                      "!1p,!file")
--debug-file <path>                   Write debug logs to a specific file path
                                      (implicitly enables debug mode)

claude --debug-file /tmp/claude-debug.log
grep -i "BETA_TRACING" /tmp/claude-debug.log

次の表は、症状から原因を当てはめる早見表です。

内容を送るリスクの見立て

detailed beta tracingは、モデル応答やツール出力、システムプロンプトといった内容を伴う情報をトレーシングバックエンドへ送る機能です。OTEL_LOG_USER_PROMPTSやOTEL_LOG_TOOL_CONTENTをすべて有効にすると、会話の中身がそのままコレクターに届きます。

有効化する前に、送信先のコレクターと後段のログ基盤が、どこまでアクセス制御されているかを確かめる選択肢があります。hookの成否だけ追えれば足りる場合は、内容系のゲート変数を足さずに2変数だけで始める運用もできます。

まとめ

hookの実行状況をスパン単位で追いたいだけなら、2変数にゲート変数を足さない構成から始められます。プロンプトやツール出力まで送る場合は、送信先の統制と、管理設定でのコレクター固定がv2.1.251以降かどうかを先に確かめます。すでにHooksをHTTPエンドポイントで受ける構成なら、hookの成否をスパンでも並べて見られます。