Claude Code × OpenTelemetry完全ガイド——AIコーディングを観測する方法【2026年最新】

Claude CodeにはOpenTelemetry（OTel）を使った観測機能が標準搭載されており、トークン使用量・コスト・ツール実行の成否をPrometheusやGrafana、Datadog、Honeycombに送信できます。本記事では公式ドキュメントを一次ソースに、セットアップから主要バックエンド連携、ダッシュボードで見るべき指標までを網羅的に解説します。

チームでClaude Codeを導入するSRE・プラットフォーム担当・エンジニアリングマネージャーが、最短で本番監視基盤に到達するための実装ガイドとしてお役立てください。

OpenTelemetryとは何か（30秒サマリ）

OpenTelemetry（OTel）は、メトリクス・ログ・トレースという3種類のテレメトリーを統一的に収集・転送するためのオープンソース規格です。CNCF（Cloud Native Computing Foundation）がホストしており、2026年時点で事実上の業界標準となっています。

OpenTelemetryの最大の利点は、アプリケーション側のコード変更なしにバックエンドを切り替えられることです。Prometheusで自前運用していたところからDatadogへの移行、あるいはその逆も、環境変数の変更だけで実現できます。

Claude Codeはこの規格に準拠しているため、既存の監視基盤にそのまま乗せられます。

なぜClaude Codeに観測が必要か

Claude Codeは強力ですが、トークン従量課金・自律的なツール実行・外部API呼び出しという特性から、観測なしでの運用はリスクが高い領域です。

1. コスト把握

Claude Codeは1セッションで数百万トークンを消費することがあります。誰が・どのモデルで・いくら使っているかを把握できないと、月末の請求で予期せぬコストが発覚します。

2. 品質監視

Edit/Writeツールの受諾率、APIエラー率、リトライ頻度などを継続監視することで、「Claudeの提案が採用されているか」「プロンプト設計に問題がないか」を定量的に把握できます。

3. セキュリティ・ガバナンス

どのツールが・いつ・誰によって実行されたかを監査ログとして残すことで、不適切な操作の検知やインシデント調査に活用できます。

Claude Codeが収集できるメトリクス・イベント一覧

Claude Codeが標準で出力するメトリクスとイベントは、公式ドキュメント（code.claude.com/docs/en/monitoring-usage）で定義されています。

メトリクス（Metrics）

イベント（Logs）

• claude_code.user_prompt — ユーザープロンプト発生
• claude_code.tool_result — ツール実行結果（tool_name, success, duration_ms, error）
• claude_code.api_request — API呼び出し（model, cost_usd, duration_ms, input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, speed）
• claude_code.api_error — APIエラー（status_code, attempt）
• claude_code.tool_decision — ツール承認判断
• claude_code.plugin_installed — プラグインインストール
• claude_code.skill_activated — スキル起動

イベントにはprompt.id属性が付与され、複数イベントを同一プロンプトに紐付けられます。メトリクスには付きません（カーディナリティ爆発を防ぐため）。

サービス情報

• service.name=claude-code
• Meter Name: com.anthropic.claude_code

セットアップ手順

必須の環境変数

まず、テレメトリーを有効化するために最低限必要な環境変数を設定します。

# テレメトリー有効化（必須）
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# エクスポーターの指定
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp

# OTLPエンドポイント（例: ローカルのOpenTelemetry Collector）
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

主要な環境変数リファレンス

プロンプト本文やツール引数は機密情報を含む可能性があるため既定で無効になっている点に注意してください。監査要件がある場合のみ明示的に有効化します。

メトリクスとログで送信先を分ける

別バックエンドに振り分ける場合は専用の環境変数を使用します。

export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://prometheus.example.com/otlp
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://logs.example.com/otlp

マルチチーム運用時のリソース属性

部署やチーム単位でコストを按分する場合、OTEL_RESOURCE_ATTRIBUTESでタグを付けます。

export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

スペース不可・カンマ区切り厳格などフォーマット要件があるため、設定後はotel-cli等で実際の送信データを確認することをおすすめします。

動的ヘッダ（トークン自動更新）

クラウドバックエンドの短命トークンに対応するため、.claude/settings.jsonで更新スクリプトを指定できます。

{
  "otelHeadersHelper": "/usr/local/bin/refresh-otel-token.sh"
}

既定の更新間隔は29分で、CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MSで変更可能です。

主要バックエンドとの連携例

Prometheus（自前運用）

ローカルのPrometheusに直接スクレイプさせる最も手軽な構成です。

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus
# 既定で 0.0.0.0:9464/metrics がexposed

累積型（Cumulative）バックエンドを使う場合は以下を追加します。

export OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=cumulative

Grafana Cloud / Grafana OSS

Grafanaは公式のClaude Code用ダッシュボード（Dashboard ID 25052）を用意しています。OTLPでGrafana Cloudに直送する例は以下の通りです。

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp-gateway-prod-xx.grafana.net/otlp
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic <base64エンコードトークン>"

Datadog

DatadogはAI Agents ConsoleでClaude Code Monitoringをプレビュー提供しており、ユーザー別・モデル別のコスト、レイテンシ、エラー率を一覧できます。

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.datadoghq.com
export OTEL_EXPORTER_OTLP_HEADERS="DD-API-KEY=<APIキー>"

Honeycomb（分散トレース向け）

Bash/PowerShellサブプロセスのトレースまで含めて見るなら、Tracesベータを併用します。

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io:443
export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=<APIキー>"

CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1を有効にすると、サブプロセスがTRACEPARENTを自動継承し、W3C Trace Contextに準拠した親子関係でトレースが形成されます。

その他のバックエンド

New Relic / SigNoz / OpenObserve / VictoriaMetricsもOTLP経由で連携可能です。Amazon Bedrock経由でClaude Codeを運用している場合は、Anthropic公式のBedrock向け観測ガイドも公開されています。

ダッシュボードで見るべき重要指標

導入直後にまず見るべき指標を、優先度順に整理します。

コスト系（最優先）

• 日次・週次コスト：claude_code.cost.usageをmodel属性で分解
• ユーザー別コスト上位10：OTEL_RESOURCE_ATTRIBUTESでユーザータグを付与して集約
• キャッシュヒット率：claude_code.token.usage{type=cacheRead} ÷ {type=input}

キャッシュヒット率が低い場合、プロンプト設計（システムプロンプトを先頭に置く等）を見直すだけで大幅にコストが下がります。

品質系

• Edit受諾率：claude_code.code_edit_tool.decisionのaccept比率。50%を下回る場合、プロンプトやコンテキストに問題がある可能性あり
• APIエラー率：claude_code.api_errorをステータスコード別にグルーピング
• リトライ回数分布：claude_code.api_errorのattempt属性

パフォーマンス系

• ツール実行時間：claude_code.tool_resultのduration_ms
• API応答速度：claude_code.api_requestのspeed

チーム開発での活用ユースケース

1. 部署別コスト按分

OTEL_RESOURCE_ATTRIBUTESでcost_centerやteam.idを付与することで、月次コストを部署単位で分割集計できます。FinOps観点で経営報告に活用できます。

2. 品質ゲートとしての受諾率監視

Edit受諾率が特定のリポジトリで極端に低い場合、そのリポジトリのコンテキスト設計（CLAUDE.md、サブエージェント定義）に問題がある可能性があります。しきい値アラートを設定して早期検知しましょう。

3. セキュリティ監査

claude_code.tool_decisionイベントで、どのツールがいつ誰によって承認されたかを記録できます。Bashツールの実行ログを長期保管することで、コンプライアンス要件に対応できます。

4. プラグイン/スキル普及状況の把握

claude_code.plugin_installedとclaude_code.skill_activatedから、社内で作成したカスタムスキルの利用状況を可視化できます。

トラブルシューティング・注意点

メトリクスが送信されない

1. CLAUDE_CODE_ENABLE_TELEMETRY=1が環境変数として渡っているか確認
2. OTEL_METRICS_EXPORTER=consoleに一時的に切り替え、標準エラー出力にメトリクスが出るか確認
3. コレクタ側のログでOTLP接続エラーが出ていないか確認

累積型バックエンドで値が0のまま

Claude Codeのメトリクスは既定でdelta型です。Prometheus互換バックエンドを使う場合、OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=cumulativeに切り替えてください。

カーディナリティ爆発

既定でsession.idとaccount.uuidがメトリクス属性に含まれます。メトリクス課金型のバックエンド（Datadog等）で費用が跳ね上がる場合、以下を設定してください。

export OTEL_METRICS_INCLUDE_SESSION_ID=false
export OTEL_METRICS_INCLUDE_ACCOUNT_UUID=false

プロンプト本文が機密情報を含む

既定ではOTEL_LOG_USER_PROMPTSとOTEL_LOG_TOOL_DETAILSは無効です。有効化する場合は、送信先バックエンドでのアクセス制御・マスキング設定を事前に整備してください。

まとめ

Claude CodeのOpenTelemetry対応は、環境変数を数行設定するだけで既存の監視基盤にフィットする実用レベルに達しています。

• 最初はOTEL_METRICS_EXPORTER=consoleで出力を確認
• 次にPrometheusまたはGrafana CloudでPOC
• 本番ではDatadog/Honeycomb等に集約し、コスト・品質・セキュリティの3軸でダッシュボード化

トークン従量課金・自律エージェントという特性上、観測なしのClaude Code運用は推奨されません。本記事のセットアップを土台に、チームに合わせた監視基盤を構築してみてください。

参考リンク

• Claude Code Monitoring公式ドキュメント
• anthropics/claude-code-monitoring-guide（GitHub）
• Grafana Dashboard ID 25052: Claude Code