# Claude Codeの利用量をOTelで可視化する最小構成

> Claude CodeはOpenTelemetryで8種のメトリクスを出力できる。中小企業が管理設定で収集を始め、プロンプト本文を送らず利用量と費用を見る最小構成を示す。

- Canonical: https://kuucorp.com/blog/claude-code-opentelemetry-usage-cost-monitoring-smb/
- Date: 2026-10-12
- Last modified: 2026-10-12
- Publisher: Kuu株式会社 (https://kuucorp.com)

---
Claude Codeを数人に配ったところ、月末まで誰がどれだけ使ったか分からない。かといって、監視のためにプロンプトの中身まで集めるのは社内の抵抗が大きい。

Claude Codeは、OpenTelemetry（OTel）という標準規格でメトリクスとイベントを出力する機能を備えている。本記事では、中小企業のIT担当が**本文を集めずに利用量と費用だけを見る**最小構成を整理する。コスト計測の全体設計は[AI FinOps](/blog/ai-finops-token-cost-instrumentation/)、監査証跡の記録は[hooksによる監査ログ](/blog/claude-code-hooks-audit-policy-enforcement-smb/)も参照してほしい。

## Claude Codeはどんなデータを出力できるのか

> 公式ドキュメントによると、Claude Codeはメトリクス・ログイベント・トレース（ベータ）の3種を出力でき、収集は初期状態で無効です。

メトリクスは8種類で、`claude_code.session.count`、`claude_code.cost.usage`（単位はUSD）、`claude_code.token.usage`、`claude_code.active_time.total`、`claude_code.commit.count`、`claude_code.pull_request.count`、`claude_code.lines_of_code.count`、`claude_code.code_edit_tool.decision`が並ぶ。利用量と費用の集計にはこれで足りる。

イベントは`claude_code.api_request`や`claude_code.tool_result`、`claude_code.tool_decision`など16種が定義されている。トレースは`CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`が必要なベータ機能で、スパン名や属性は変わる可能性がある。

## 最小構成はどう設定するのか

> 必要なのは`CLAUDE_CODE_ENABLE_TELEMETRY=1`と、エクスポーターおよびOTLPエンドポイントの指定の3点です。

最初は個人のシェルで動作を確かめる。

```bash
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=none
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_METRIC_EXPORT_INTERVAL=10000
claude
```

確認は、バックエンドに`claude_code.session.count`が届くかで行う。届かない場合は`claude --debug-file <path>`で起動し、`[3P telemetry]`のエラーを探す。`[Anthropic telemetry]`の行はAnthropic側の別系統であり、自社の設定不備を示すものではない。

動作を確認したら`OTEL_METRIC_EXPORT_INTERVAL`を既定の60000msに戻す。ログの既定間隔は5000msである。

## 全社員に強制するにはどうするか

> 管理設定の`env`にOTel変数を書けば全員に配布でき、収集先のエンドポイントは開発者側で上書きされません。

管理設定に同じ変数を`env`として記述する。公式ドキュメントによれば、管理設定が`OTEL_EXPORTER_OTLP_ENDPOINT`を指定すると、開発者が個別に設定した信号別エンドポイントは起動時に除去される。

注意点は2つある。1つ目はエクスポーターの選択が固定されない点で、`OTEL_METRICS_EXPORTER`も管理設定に入れないと利用者が`none`や`console`へ切り替えられる。2つ目は、リポジトリ内の`.claude/settings.json`ではOTel変数が無視される点で、リポジトリ側から収集を有効化したり送信先を変えたりはできない。この点は、悪意あるリポジトリにテレメトリを乗っ取られないための仕様として働く。管理設定の配布経路ごとの抜け道は[管理設定が効かない5つの経路](/blog/claude-code-managed-settings-bypass-paths-smb/)にまとめた。

## 何を集めてはいけないのか

> プロンプト本文やBashコマンドは、初期状態では収集されません。送信するフラグは明示的に有効化したときだけ働きます。

内容を送るフラグはすべて既定で無効である。

- `OTEL_LOG_USER_PROMPTS=1`: プロンプト本文を含める
- `OTEL_LOG_TOOL_DETAILS=1`: Bashコマンド、MCPサーバー名、ツール入力を含める
- `OTEL_LOG_RAW_API_BODIES`: API要求と応答のJSON全体を出す。会話履歴がすべて含まれ、有効にすると他の3フラグ分の内容も出ることに同意したとみなされる

費用と利用量の把握が目的なら、これらは設定しないままでよい。例外として、不正なコマンド実行の調査が必要な場合のみ`OTEL_LOG_TOOL_DETAILS`を、保存先と閲覧者を限定したうえで検討する。

また`user.id`はClaudeアカウントから導出されない匿名の識別子だが、`user.email`は取得できる場合に付与される。個人別の集計をする際は、社内規程で目的を明示しておく。

メトリクスのカーディナリティ（ラベルの種類数）にも注意したい。`OTEL_METRICS_INCLUDE_SESSION_ID`の既定は`true`で、セッションごとに系列が増える。バックエンドの課金が系列数に比例する場合は`false`にする。

## SDKで動かすエージェントも同じ方法で見られるのか

> Agent SDKはClaude Code CLIを子プロセスとして動かすため、同じ環境変数でテレメトリを出力できます。

SDK自身はテレメトリを生成せず、設定を子プロセスに渡してCLIが直接コレクターへ送る。本番では、コンテナやオーケストレーターのプロセス環境に変数を置く方式が推奨されている。

SDK経由では`console`エクスポーターを使わない。標準出力がSDKのメッセージ経路と衝突するためで、ローカル確認にはOpenTelemetry Collectorを立てる。送信に失敗してもエージェントは通常どおり動き、エラーも出ないため、`CLAUDE_CODE_OTEL_DIAG_STDERR=1`で診断を有効にしておくと原因を追える。

サービス名は既定で`claude-code`になる。複数のエージェントを同じコレクターに送る場合は、`OTEL_SERVICE_NAME`と`OTEL_RESOURCE_ATTRIBUTES`で区別する。

## まとめ

> 最小構成は、メトリクスだけをOTLPで送り、内容系フラグを有効にしない設定です。これで利用量と費用の集計は成立します。

次の順で進める。

1. 個人のシェルで`claude_code.session.count`の到達を確認する
2. 管理設定の`env`に、エクスポーターとエンドポイントの両方を入れて配布する
3. 内容系フラグを設定せず、`claude_code.cost.usage`を週次で確認する

Claude Codeの利用統制や監視基盤の設計でお困りの場合は、[AIエージェント運用管理サービス](https://kuucorp.com/services/ai-ops/)にご相談ください。

## 参考

- [Monitoring - Claude Code Docs](https://code.claude.com/docs/en/monitoring-usage)
- [Observability with OpenTelemetry - Claude Code Docs](https://code.claude.com/docs/en/agent-sdk/observability)