環境変数

TRACEPARENT

非対話型セッションにおいて、外部プロセスから渡されたW3C標準のトレースコンテキストを読み取り、スパンを関連付けます。

使い方・用途

  • CI環境やマイクロサービス等の上位プロセスからClaude Codeを呼び出す際、AIの動作を親プロセスのトレースツリーに子スパンとして連結するために使用します。
  • AIが実行するBashコマンド等のサブプロセスに対してもこの情報を伝播させ、システム全体のEnd-to-Endでの可視化と詳細なデバッグを実現します。
英語原文(公式ドキュメントより)

In Agent SDK and non-interactive sessions started with -p, Claude Code also reads TRACEPARENT and TRACESTATE from its own environment when starting each interaction span. This lets an embedding process pass its active W3C trace context into the subprocess so Claude Code's spans appear as children of the caller's distributed trace. Interactive sessions ignore inbound TRACEPARENT to avoid accidentally inheriting ambient values from CI or container environments.

関連する変更履歴

v2.1.110(1件)

Changed
SDKおよびヘッドレスセッションにおいて、環境変数からTRACEPARENT/TRACESTATEを読み取り、分散トレーシングのリンクに対応
英語原文を表示
SDK/headless sessions now read TRACEPARENT/TRACESTATE from the environment for distributed trace linking

変更前

SDK経由や非対話モードで実行している際、外部のモニタリングツールなどでシステム全体のトレースを確認しても、Claude Code内部の挙動と紐付けることが困難でした。

変更後

W3C標準のトレースコンテキスト環境変数をサポートし、上位のプロセスから渡されたトレース情報をClaude Code内のスパンと統合して出力できるようになりました。

ユーザーへの恩恵

大規模な自動化パイプラインやマイクロサービスの中でClaude Codeを使用する際、全体の処理フローとAIの挙動を一貫して可視化・デバッグできるようになります。

関連ドキュメント

v2.1.98(1件)

Added
OpenTelemetry（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

変更前

AIが実行したコマンドの詳細なログ（スパン）が、Claude Code 本体のトレースと分離されてしまい、全体の実行フローを追跡するのが困難でした。

変更後

本体とサブプロセスのトレーシング情報が連結され、分散トレーシングツール上で一連の動作として可視化されます。

ユーザーへの恩恵

複雑なタスクのデバッグやパフォーマンス分析において、どのツールがどのタイミングで時間を要したかを正確に診断できるようになります。

関連ドキュメント

v2.1.97(1件)

Improved
Settings
BashツールのOpenTelemetryトレースを改善しました。トレーシング有効時、サブプロセスがW3C標準のTRACEPARENT環境変数を継承するようになりました。
英語原文を表示
Improved Bash tool OTEL tracing: subprocesses now inherit a W3C TRACEPARENT env var when tracing is enabled

変更前

Claudeが実行したシェルコマンドからさらに呼び出されるコマンド（ビルドツールなど）の動きが、分散トレーシング上で繋がらず、詳細な解析が難しい状態でした。

変更後

親プロセスから子プロセスへとトレースIDが伝播し、一連の動作を一つの流れとして監視できるようになりました。

ユーザーへの恩恵

大規模なシステム開発において、Claudeが行った変更がどのようにビルドやテストに影響したかを、組織全体の観測プラットフォームで正確に追跡・分析できます。

関連ドキュメント