Claude Media
Claude CodeのOpenTelemetryで利用量とコストを可視化

Claude CodeのOpenTelemetryで利用量とコストを可視化

Claude CodeのOpenTelemetry連携で利用量・コスト・監査ログを可視化する設定手順と、アップグレード時にassistant_responseが意図せず記録される落とし穴をまとめます。

最初に押さえる4つの環境変数

結論から言うと、必須なのはCLAUDE_CODE_ENABLE_TELEMETRY=1と信号ごとのエクスポーター指定で、otlpを選ぶならプロトコル(OTEL_EXPORTER_OTLP_PROTOCOL)も要ります。プロンプト本文とトレースは、別の変数を明示しない限り送られません。

環境変数役割既定の挙動
CLAUDE_CODE_ENABLE_TELEMETRY役割テレメトリ収集の必須スイッチ(値は1)既定の挙動未設定では収集されない
OTEL_METRICS_EXPORTER役割メトリクスの送り先(otlp・prometheus・console・none)既定の挙動指定が必要(otlpならプロトコル指定も必須)
OTEL_LOG_USER_PROMPTS役割プロンプト本文をイベントに含める(1で有効)既定の挙動無効(本文は<REDACTED>)
CLAUDE_CODE_ENHANCED_TELEMETRY_BETA役割スパン(トレース)の必須スイッチ(値は1)既定の挙動無効

トレースを使うときは、CLAUDE_CODE_ENABLE_TELEMETRY=1とCLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1の両方が要ります。バックエンドが累積値を前提にする場合は、メトリクスのtemporalityをcumulativeに変える設定も検討します。

はじめに

チーム全体のClaude Code利用状況は、開発者一人ひとりが/costコマンドを個別に確認するだけでは全体像が見えてきません。OpenTelemetry(OTel)経由でメトリクスとイベントを外部バックエンドに送れば、誰がどれだけ使い、コストがどこに寄っているかをダッシュボード上で追えるようになります。キャッシュ書き込みの寿命別の内訳はcache_creation_5m_tokensの記事で扱っています。

前提条件は次の3つです。

項目必要な状態
Claude Code必要な状態機能ごとに必要なバージョンが異なる(本文で明記)
バックエンド必要な状態OTLP受信可能な収集基盤(Prometheus、Honeycomb、Datadog、Grafana Cloud等)
環境変数の設定権限必要な状態シェル、または管理設定(managed settings)ファイルへの書き込み権限

管理者は組織全体の設定をmanaged settingsファイル経由で強制でき、開発者個人が任意のエンドポイントへ向け先を変えることを防げます。

ステップ1: テレメトリを有効にしてエクスポート先を設定する

最小構成は環境変数5つです。

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

CLAUDE_CODE_ENABLE_TELEMETRYが有効化の必須スイッチで、これだけではどこにも送られません。otlpエクスポーターを使うときは、OTEL_EXPORTER_OTLP_PROTOCOL(または信号別のプロトコル変数)も必ず指定します。Claude Codeにはプロトコルの既定値がないためです。メトリクスはOTEL_METRICS_EXPORTER、イベント(ログ)はOTEL_LOGS_EXPORTERと、送りたい信号ごとにエクスポーターを指定します。どちらもnoneを指定すれば個別に無効化できるので、メトリクスだけ欲しい場合はログ側をnoneにしておくと送信量を絞れます。メトリクスをPrometheusで直接スクレイプする構成は、OTEL_METRICS_EXPORTERをprometheusにする手順にあります。

エクスポート間隔にも既定値があります。メトリクスはOTEL_METRIC_EXPORT_INTERVALが既定60000ms(60秒)、イベントはOTEL_LOGS_EXPORT_INTERVALが既定5000ms(5秒)です。設定確認中はメトリクスの反映を待つ時間が長く感じられるため、動作確認時だけ値を短く設定して間隔を詰めておくと反応を確かめやすくなります。

設定が届いているかどうかは2つのシグナルで確認できます。claude_code.session.countメトリクスはセッション開始時に発行されます。claude_code.user_promptイベントはプロンプト送信時に発行されます。どちらかがバックエンドに届いていれば成功です。

手順

何も届かないときの切り分け順

  1. 1

    環境変数の置き場所を疑う

    リポジトリの.claude/settings.jsonと.claude/settings.local.jsonに書いたOTel用の変数は、一部が無視されます(v2.1.282以降)。有効化や送信先の指定がそれで、シェルか~/.claude/settings.json、管理設定のどれかに移します。ただしエクスポーター選択をnoneにする指定だけは効きます。リポジトリ側で信号が止められていないかも見てください。/statusかclaude doctorで、無視された変数名や止められた変数名を確認できます。

  2. 2

    プロトコルの指定漏れを見る

    OTEL_EXPORTER_OTLP_PROTOCOLが未設定だと、otlpを選んでいても送れません。

  3. 3

    デバッグログでエクスポートエラーを探す

    claude --debug-file <path>で起動し、ログに[3P telemetry]のエクスポートエラーが出ていないかを確認します。--debug-fileはclaude --helpにも載っており、v2.1.287で確認しました。

  4. 4

    管理設定による上書きを確認する

    管理設定でOTEL_EXPORTER_OTLP_*が指定されていると、手元で設定した値のうち衝突するものが、起動時に取り除かれます。この削除はデバッグログに警告として残ります。

管理設定で送信先を固定すると何が消えるか

管理設定にOTEL_EXPORTER_OTLP_*系の変数を書くと、Claude Codeは起動時に、衝突する開発者側の変数を取り除きます。取り除く範囲は、管理設定に書いた変数の種類で決まります。

くらべる

管理設定に書いた変数ごとの効き方

開発者側の指定が消える

取り除かれる

  • OTEL_EXPORTER_OTLP_ENDPOINTを書くと、信号別のエンドポイント指定がすべて消えます
  • OTEL_EXPORTER_OTLP_PROTOCOLを書くと、信号別のプロトコル指定がすべて消えます
  • OTEL_EXPORTER_OTLP_HEADERSなどの認証情報を書くと、信号別の同じ変数に加えて、汎用・信号別のエンドポイントも消えます
個別キーの優先順位のまま

残る

OTEL_METRICS_EXPORTER・OTEL_LOGS_EXPORTER・OTEL_TRACES_EXPORTERは通常のキー単位の優先順位に従います。開発者がnoneやconsoleに切り替えられるので、固定したいなら管理設定にも書きます。

認証情報が出てくると送信先も消える理由は、トークンが管理者の選んでいないコレクターへ届くのを防ぐためです。この削除が変えるのは送信先で、収集される内容は変わりません。時期による挙動の差もあります。v2.1.217より前は全変数がキー単位で独立に解決され、シェルで設定した信号別エンドポイントが管理側のコレクターを迂回できました。複数の管理設定ソースをまたぐときは、OTEL_LOGS_EXPORTERがテレメトリ単位、ほかの2つのエクスポーター選択キーがキー単位でマージされます(v2.1.223以降)。BETA_TRACING_ENDPOINTもv2.1.251より前は迂回できました。v2.1.251以降は、デスクトップアプリやself-hosted runnerの起動側が指定したOTLPエンドポイントも、同様に固定されます。

ステップ2: 利用量とコストのメトリクスを読む

Claude Codeが発行する主なメトリクスは8種類です。

メトリクス何が分かるか
claude_code.session.count何が分かるかセッション開始数(採用率の推移)
claude_code.token.usage何が分かるか入力/出力/キャッシュ別のトークン消費量
claude_code.cost.usage何が分かるかセッションのコスト(USD、概算値)
claude_code.lines_of_code.count何が分かるか追加/削除された行数
claude_code.pull_request.count何が分かるか作成されたPR/MR数
claude_code.commit.count何が分かるか作成されたgitコミット数
claude_code.code_edit_tool.decision何が分かるかコード編集ツールの提案が承認/却下された件数
claude_code.active_time.total何が分かるか実際に活動していた時間の合計

claude_code.cost.usageとclaude_code.token.usageはskill.name・plugin.name・agent.nameの属性を持ちます。どのスキルやサブエージェントがコストを押し上げているかまで分解できるということです。ただしコストメトリクスはあくまで概算です。ストリーミング応答は1回分だけ数えられます。v2.1.214より前は、ANTHROPIC_BASE_URLの先のゲートウェイが使用量を複数フレームに分けて流すと、余分なフレーム数だけ1リクエスト分が上乗せされました。古い版が混在する集計を読むときは、この水増しを疑います。正式な請求額は、実際に契約しているプロバイダー(Claude Console、Amazon Bedrock、Google CloudのAgent Platformなど)側の数字を正とします。契約形態別の料金の考え方はClaude Codeの料金ガイドにまとめています。

コスト急増や異常なトークン消費を早期に検知したい場合は、属性でセグメント分割してアラートを組むのが定石です。標準属性に加え、コスト・トークンのメトリクスが持つmodelやquery_source(main/subagent/auxiliary)で分割できます。model属性はclaude_code.lines_of_code.countではv2.1.172以降で付きます。モデル別のコミット数まで分解したい場合は、session.idでトークンやコストのメトリクスと突き合わせます。その上でquery_sourceがmainの行だけに絞り込みます。サブエージェントやauxiliaryのリクエストをそのまま合算すると、コミットしていないモデルに手柄を誤帰属してしまいます。

メトリクスだけでは、1回のプロンプトで何が起きたかは追えません。イベント側にはprompt.idというUUIDが付き、1回のプロンプトから生じたuser_prompt・api_request・tool_resultをまとめて引けます。順序の判定にはevent.sequenceを使いたくなりますが、この値はセッション単位でなくプロセス単位のカウンターです。/clearを挟んでも数え続け、セッションを再開すると別プロセスの値を引き継ぎます。同じセッション内で後のイベントのほうが小さい値になることもあるため、並べ替えはevent.timestampを主、event.sequenceを同時刻の補助にします。

入力トークンの数え方にも癖があります。claude_code.token.usageのinputとapi_requestのinput_tokensは、キャッシュの読み取りと書き込みを含みません。OpenTelemetryのGenAI規約が想定する入力トークン総数に合わせたいときは、input・cacheRead・cacheCreationの3種類を足します。Claude Code自身はgen_ai.usage.*属性を出力しません。コレクターで換算する例はGenAI規約への換算手順にあります。

ステップ3: 監査・SIEM向けにイベントを設定する

OpenTelemetryのイベント(ログ)は、Claude Codeの操作を誰が行ったかまで追跡できる監査データです。認証済みのユーザー情報(user.email・user.account_uuid・organization.id)が標準属性として各イベントに付きます。そのためBashコマンド・ファイル編集・MCP呼び出しは、すべて実行した開発者本人に紐づきます。組織のセキュリティ設計全体との位置付けはClaude Codeセキュリティ・権限ガイドも参考にしてください。

MCPサーバーの呼び出し詳細まで監査したい場合は、OTEL_LOG_TOOL_DETAILS=1を追加します。これを設定するとtool_resultとtool_decisionイベントにサーバー名・ツール名・呼び出し引数が乗るようになります。設定しない場合、ユーザーが追加したMCPサーバーのtool_nameは常に文字列"mcp_tool"に丸められ、引数の内容は省かれます。SIEMで引く値はこのmcp_toolです。コストやトークンのメトリクスに付くmcp_server.nameなどの属性も、既定ではcustomやthird-partyといった代替値になります。v2.1.273より前は、このフラグを立てても代替値のままの属性がありました。SIEMへ転送する場合はOTEL_EXPORTER_OTLP_LOGS_ENDPOINTを専用のOTLP受信エンドポイントに向けるだけで済みます。メトリクスとは別系統でイベントだけを送ることもできます。届いたかどうかは、そのセッションでプロンプトを1つ送り、SIEM側でclaude_code.user_promptを探して確認します。Claude Codeが出すのは生のイベントストリームだけです。異常検知やセッションをまたぐ突き合わせ、アラートはSIEMやバックエンド側の仕事になります。ツール出力まで載せるOTEL_LOG_TOOL_CONTENTとの違いは別記事で整理しています。

SIEMの調査で頻出するのが、APIが失敗し続けたセッションの切り分けです。内部のリトライは個別のイベントにならず、諦めた時点でclaude_code.api_errorが1件だけ出ます。attempt属性が総試行回数で、CLAUDE_CODE_MAX_RETRIESの既定は10回、上限は15回です。リトライを使い切った一時エラーでは、attemptは既定で11になります。それより小さい値なら、400のような再試行されないエラーか、独自の試行枠を持つ原因です。AWSやGoogle Cloudの認証情報の読み込み失敗は、最大2回しか再試行されません。回復したセッションと止まったセッションは、session.idで束ねて、エラーの後にapi_requestが続くかどうかで見分けます。

さらに踏み込むならOTEL_LOG_RAW_API_BODIES=1があります。Messages APIのリクエストとレスポンスのJSON全体がapi_request_body・api_response_bodyイベントに乗ります。本文には会話履歴がまるごと入るので、有効化はプロンプトやツール内容の記録に同意したのと同じ扱いになります。file:<dir>を指定すると、切り詰めのない本文をディスクへ書き出し、イベントには参照だけを残せます。

直接APIキーで認証している場合や、Amazon Bedrock・Google CloudのAgent Platform・Microsoft Foundry経由の場合は事情が異なります。Claudeアカウントに紐づく識別情報がセッションに存在しないため、user.idとsession.idしか埋まりません。ユーザー単位の追跡が必要な組織では、OTEL_RESOURCE_ATTRIBUTESでユーザー識別子を自前で付与する運用が案内されています。管理設定のファイルか起動ラッパーでユーザーごとに値を差し込み、enduser.id=...のような属性を足します。

トレース(ベータ)でリクエストの流れを追う

メトリクスとイベントに加えて、分散トレーシングもベータで提供されています。1つのユーザープロンプトが引き起こしたAPIリクエストとツール実行を、1本のトレースとしてつなげて可視化する機能です。既定では無効です。CLAUDE_CODE_ENABLE_TELEMETRY=1に加えてCLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1を設定します。あとはOTEL_TRACES_EXPORTERで送信先を選ぶだけです。スパンは既定で、プロンプトの文面とツール入力、ツール内容を伏せます。出すにはOTEL_LOG_USER_PROMPTS=1・OTEL_LOG_TOOL_DETAILS=1・OTEL_LOG_TOOL_CONTENT=1を個別に立てます。

エンドポイントやプロトコル、認証ヘッダーの指定はメトリクス・イベントと共通のOTLP設定を使い回せます。特定のツール呼び出しがどこで時間を食っているか、どのAPIリクエストがどのプロンプトに紐づくかを1リクエスト単位で追いたい場合に向いており、集計値だけでは見えないボトルネックの特定に役立ちます。常時有効にすると送信量が増えるため、調査したい期間だけ絞って有効化する運用が現実的です。

トレースを有効にすると、BashとPowerShellのサブプロセスには、実行中のツールスパンのW3CトレースコンテキストがTRACEPARENT環境変数で渡ります。スクリプトがこの変数を読めば、自分のスパンを同じトレースの下にぶら下げられます。モデルへのリクエストにもtraceparentヘッダーが付きます。ヘッダーとサブプロセスのTRACEPARENTは、どちらもANTHROPIC_BASE_URLが未設定かAnthropic APIを指すときだけ付きます。独自のプロキシ経由でも伝播させたいときはCLAUDE_CODE_PROPAGATE_TRACEPARENT=1を設定します。

Claude apps gateway経由でClaude Codeを使っている場合は、ここまでのクライアント側OTel設定とは別に、ゲートウェイ自身のテレメトリ転送設定があります。telemetry.forward_toで信号ごとに宛先を分ける方法や、ゲートウェイが自動配信する環境変数の中身はClaude apps gatewayのテレメトリ設定にまとめています。

OTEL_LOG_ASSISTANT_RESPONSESを設定しないと何が起きるか

ここが実務で最も踏みやすい落とし穴です。v2.1.193でassistant_responseイベントが追加され、Claudeの応答テキストをログに残せるようになりました。この応答テキストは既定で<REDACTED>に伏せられ、OTEL_LOG_ASSISTANT_RESPONSES=1を明示しない限り中身は出ません。

問題は未設定時の挙動です。OTEL_LOG_ASSISTANT_RESPONSESを一度も設定していない環境では、値はOTEL_LOG_USER_PROMPTSの設定に連動します。プロンプトのロギングだけを目的に、以前からOTEL_LOG_USER_PROMPTS=1にしていた組織があるとします。この組織がClaude Codeをv2.1.193以降にアップグレードした瞬間、設定を何も変えていないのに応答テキストの記録が新たに始まります。プロンプトだけ集めるつもりが、Claudeの出力内容まで一緒にログ基盤へ流れ込む形です。

応答だけを確実に伏せたい場合は、OTEL_LOG_ASSISTANT_RESPONSES=0を明示的に設定します。これでプロンプトのログは維持したまま、応答テキストだけを<REDACTED>のままにできます。v2.1.287でuser_promptイベントに加わったprompt_textはpromptの写しなので、promptを落とす場合やマスクする場合は同じ扱いにします。記録されるのは応答のテキストブロックだけで、思考ブロックとツール呼び出しは含まれません。応答内容には機密情報や個人情報が含まれる可能性があるため、ログ基盤へのアクセス権限を持つ人の範囲を、プロンプトロギングを有効化した時点で見直しておくと安全です。この機能自体の変更点はv2.1.193のリリースノートにもまとまっています。

コスト分析でよくあるつまずき

Prometheusでスクレイプがエラーになる場合、OTEL_METRICS_EXPORTERの指定を確認します。prometheus単体指定かotlp,prometheusのような複数指定かで挙動が変わるためです。単体指定時はUSD・tokens・秒の単位表記が、Prometheusのテキスト形式として妥当であり続けるため自動的に省かれ、複数指定時は単位が残ります(なお# UNIT行によるOpenMetrics形式での単位表記はv2.1.216より前の挙動です)。

AzureモニターなどOTLPのHTTP受信口が411 Length Requiredや400を返す場合は、Claude Codeの版を見ます。http/protobufとhttp/jsonの送信は、v2.1.191からv2.1.211までチャンク転送でした。v2.1.212以降はContent-Lengthを付けて送ります。

まとめ

メトリクスだけで始め、監査が要る段階でイベント、ボトルネック調査でトレースと足していく順が扱いやすい構成です。OTEL_LOG_USER_PROMPTS=1で運用中の環境は、アップグレード前にOTEL_LOG_ASSISTANT_RESPONSESを明示してください。収集したメトリクスをオンコール対応まで繋げたいときはGrafana OnCallをClaudeで操作するが参考になります。

よくある質問

コンテンツの切り詰め上限は変更できますか

できます(v2.1.214以降)。CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTHは応答テキストやツール内容、システムプロンプト、生のAPI本文の上限です。UTF-16コード単位の既定値は61440(約60KB)で、属性値を64KBまでに制限するバックエンドを想定した値なので、上げるのは受け付ける先だと分かっているときだけにします。下げれば送信量を抑えられます。SDK側のOTEL_ATTRIBUTE_VALUE_LENGTH_LIMITがより小さければ、そちらの値で切り詰められます。

Bashツールから起動した別のOpenTelemetry対応アプリは、Claude Code自身のエクスポート設定を引き継ぎますか

引き継ぎません。Claude CodeはBashツールやフック、MCPサーバー、言語サーバーといったサブプロセスにOTEL_*環境変数を渡さない設計です。サブプロセス側で独自にテレメトリを送りたい場合は、コマンド内で改めて変数を指定する必要があります。

メトリクスの粒度(カーディナリティ)を下げるにはどうすればよいですか

OTEL_METRICS_INCLUDE_SESSION_IDとOTEL_METRICS_INCLUDE_ACCOUNT_UUIDは既定がtrueです。falseにするとメトリクスからその属性が外れます。OTEL_METRICS_INCLUDE_VERSIONとOTEL_METRICS_INCLUDE_ENTRYPOINTは逆に既定がfalseで、trueで追加されます。保存コストは下がりますが、ユーザー別やセッション別の分解はできなくなります。

OTelとは逆に、Anthropicへの通信をまとめて絞りたい場合はどうしますか

ここまでは自前のバックエンドへ計測を送る設定でしたが、逆にAnthropic側への通信を減らしたい組織もあります。内部エラーの送信だけを止めたいならDISABLE_ERROR_REPORTING、自動更新やテレメトリまでまとめて止めたいならCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICが対応します。どちらもOTel経由の計測パイプラインとは独立した設定です。

利用状況メトリクスの送信だけを止めたい場合はどうしますか

DISABLE_TELEMETRYに任意の値を設定すると、Anthropicへ送られる運用テレメトリのうち、利用状況メトリクス(レイテンシー・信頼性・利用パターン)を止められます。機能フラグの取得も止まります。

ここまで扱ってきた自前バックエンドへのOTelエクスポート(claude_code.session.countなど)とは別経路の設定です。対象範囲や組織一括配布の方法はDISABLE_TELEMETRYとはで確認できます。自社アプリが出したトレースから遅いスパンを探す手順は、トレースの遅いスパンをClaude Codeに探させる記事にあります。

DO_NOT_TRACKという環境変数も見かけましたが同じものですか

DO_NOT_TRACKはテレメトリと機能フラグの取得を止める、開発者向けCLIツール横断の慣習に沿った環境変数です。値を1にするとDISABLE_TELEMETRYを設定したときとまったく同じ経路が塞がれます。両者の関係と機能フラグへの副作用はDO_NOT_TRACKとはにまとめています。

参照した一次ソース

この記事の記述は、次の一次ソースと照合しています。更新時に参照先が変わった場合は一覧も更新します。

  1. code.claude.com/docs/en/monitoring-usage
  2. github.com/anthropics/claude-code/releases/tag/v2.1.193
  3. github.com/anthropics/claude-code/releases/tag/v2.1.214
  4. code.claude.com/docs/en/settings-reference
この記事を共有:XはてブLinkedIn