OpenTelemetry 連携

組織全体での Claude Code の利用状況、コスト、ツールの動作を追跡するために使います。メトリクスは時系列データとして標準のメトリクスプロトコルで、イベントは logs/events プロトコルで出力します。分散トレースの出力も選べます。

Claude Code は、メトリクス・イベント・トレースの 3 種類のデータを OpenTelemetry で出力します。

• メトリクス: 時系列データとして標準のメトリクスプロトコルで出力します。セッション数、変更したコードの行数、pull request、git commit、セッションのコスト、トークン使用量、コード編集ツールの権限の判断、合計のアクティブ時間が含まれます。
• イベント: logs/events プロトコルで出力します。prompt.id 属性を使うと、1 つのプロンプトの処理中に出たすべてのイベントを、そのきっかけとなったプロンプトに結び付けられます。
• トレース (ベータ): 出力するかどうかを選べます。

OTLP のログエクスポーターは、OTLP の受信に対応した SIEM (Security Information and Event Management) 製品、または SIEM へ転送する OpenTelemetry Collector にイベントを届けられます。

トレースは既定でオフです。有効にするには、CLAUDE_CODE_ENABLE_TELEMETRY=1 と CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 の両方を設定し、OTEL_TRACES_EXPORTER で span の送り先を選びます。

• ユーザーのプロンプトごとに claude_code.interaction というルート span が始まり、API 呼び出し、ツール呼び出し、フックの実行がその子として記録されます。
• トレースが有効なとき、Bash と PowerShell のサブプロセスは、実行中のツール実行 span の W3C トレースコンテキストを入れた TRACEPARENT 環境変数を自動で受け継ぎます。子プロセスの span は Claude Code のトレースツリーの下に親付けされます。
• SDK/ヘッドレスセッションは、分散トレースを連結するために環境変数から TRACEPARENT/TRACESTATE を読み取ります。
• claude_code.llm_request の span には agent_id / parent_agent_id 属性が含まれます。
• トレースの span には、gen_ai.provider.name、gen_ai.conversation.id、gen_ai.tool.name、error.type などの OpenTelemetry GenAI セマンティック規約の属性が付きます。

プロンプトや応答の本文など、内容に関わるデータは既定で伏せられ、環境変数でオプトインしたときだけ出力されます。

• ユーザーのプロンプト内容のログは既定で無効です。OTEL_LOG_USER_PROMPTS で有効にできます。
• span は、ユーザーのプロンプト文、ツール入力の詳細、ツールのコンテンツを既定で伏せます。含めるには OTEL_LOG_USER_PROMPTS=1、OTEL_LOG_TOOL_DETAILS=1、OTEL_LOG_TOOL_CONTENT=1 を設定します。
• user_prompt イベントでは、カスタムコマンドや MCP コマンドの名前は OTEL_LOG_TOOL_DETAILS=1 を設定しない限り伏せられます。
• モデルの応答テキストを含む claude_code.assistant_response ログイベントは、OTEL_LOG_ASSISTANT_RESPONSES=1 でない限り伏せられます。この変数が未設定のときは OTEL_LOG_USER_PROMPTS に従います。
• OTEL_LOG_RAW_API_BODIES を使うと、デバッグ用に API のリクエストとレスポンスの本文全体をログイベントとして出力できます。
• コンテンツ属性には 60 KB の切り詰め上限があり、CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH で設定できます。
• OTEL_METRICS_INCLUDE_SESSION_ID などの環境変数で、メトリクスに含める属性を選び、カーディナリティを調整できます。セッションのエントリポイント (app.entrypoint) は OTEL_METRICS_INCLUDE_ENTRYPOINT=true でオプトインします。

設定の配布と固定

• 管理者は、managed settings ファイルを通じて全ユーザーの OpenTelemetry 設定を構成できます。
• managed settings で OTEL_EXPORTER_OTLP_* 変数を設定すると、起動時に開発者が設定した競合する変数を取り除き、デバッグログに警告を残します。
• リポジトリの .claude/settings.json と .claude/settings.local.json にある OpenTelemetry のエクスポーター変数 (CLAUDE_CODE_ENABLE_TELEMETRY や OTEL_LOG_* など) は無視されます。リポジトリ側からテレメトリを有効にしたり、送り先を変えたり、内容の取得を有効にしたりはできません。
• OTEL_EXPORTER_OTLP_METRICS_ENDPOINT のようなシグナル別のエンドポイントやプロトコルの変数は、そのシグナルについて共通の変数より優先されます。OTEL_EXPORTER_OTLP_METRICS_HEADERS のようなシグナル別のヘッダー変数は、共通の OTEL_EXPORTER_OTLP_HEADERS とマージされます。
• Claude Code は、Bash ツール、フック、MCP サーバー、言語サーバーなど、自身が起動するサブプロセスに OTEL_* 環境変数を渡しません。
• Claude apps gateway のセッションは、gateway の managed settings が OTEL_EXPORTER_OTLP_ENDPOINT で指定したコレクターへ、OpenTelemetry を直接出力します。

動的な認証ヘッダー

動的な認証が必要な環境では、ヘッダーを生成するスクリプトを使えます。.claude/settings.json に otelHeadersHelper としてスクリプトのパスを追加し、スクリプトは HTTP ヘッダーを表す文字列のキーと値の組を、有効な JSON として出力するようにします。

• 動的ヘッダーが適用されるのは http/protobuf と http/json のプロトコルだけです。
• スクリプトは起動時と、その後は既定で 29 分ごとに実行されます。間隔は CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS で変えられます。
• 設定した otelHeadersHelper が失敗したときは、起動時に警告が表示されます。

データが届かないとき

claude --debug-file <path> で Claude Code を起動し、そのパスに書き出されるログを確認します。設定したエクスポーターの失敗は [3P telemetry] のエラーとして記録されます。

環境変数で設定する場合の流れです。

1. CLAUDE_CODE_ENABLE_TELEMETRY=1 を設定し、テレメトリを有効にします。
2. OTEL_METRICS_EXPORTER (otlp、prometheus、console、none) と OTEL_LOGS_EXPORTER (otlp、console、none) でエクスポーターを選びます。どちらも任意で、必要なものだけを設定します。
3. OTLP エクスポーターを使う場合は、OTEL_EXPORTER_OTLP_PROTOCOL (例: grpc) と OTEL_EXPORTER_OTLP_ENDPOINT でプロトコルとエンドポイントを設定します。
4. 認証が必要な場合は、OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token" の形で認証情報を設定します。
5. デバッグ時は OTEL_METRIC_EXPORT_INTERVAL と OTEL_LOGS_EXPORT_INTERVAL で出力の間隔を短くし、本番で使うときは元に戻します。
6. claude コマンドで Claude Code を起動します。
7. メトリクスを出力する構成では、セッション開始時に出る claude_code.session.count メトリクスがバックエンドに届いているかを確認します。ログだけの構成では、プロンプトを送信して claude_code.user_prompt イベントを確認します。