Claude Code 使用量を監視する方法｜OTel 設定とコスト追跡

Claude Code の使用量監視を支える OpenTelemetry

Claude Code は OpenTelemetry (OTel) を採用しており、メトリクス・ログ(イベント)・分散トレースの 3 系統を外部バックエンドへ送れます。OTel は CNCF(Cloud Native Computing Foundation)が標準化したオブザーバビリティプロトコルで、Prometheus・Grafana・Datadog・Splunk など主要ツールと互換性があります。

新たなダッシュボードを Anthropic 側に用意する必要はなく、手元の Prometheus・Grafana 環境にデータを集約できます。個人の費用管理から組織の部署別コスト集計まで、OTel 標準の上で監視範囲を段階的に広げられるのが大きな特徴です。

参照: Claude Code — Monitoring Usage（Anthropic 公式）

テレメトリを有効にする基本手順

最小構成で始めるには以下の 3 ステップで十分です。

1. テレメトリを有効化する

export CLAUDE_CODE_ENABLE_TELEMETRY=1

2. エクスポーター方式を指定する

export OTEL_METRICS_EXPORTER=otlp       # otlp / prometheus / console / none
export OTEL_LOGS_EXPORTER=otlp          # otlp / console / none

3. 送信先エンドポイントを設定する

export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

試験用途なら OTEL_METRICS_EXPORTER=console を指定するとターミナルにメトリクスが表示されます。エクスポート間隔はデフォルトでメトリクスが 60 秒・ログが 5 秒です。開発中は OTEL_METRIC_EXPORT_INTERVAL=10000(10 秒)に短縮しておくとデバッグがしやすくなります。

認証が必要な場合は OTEL_EXPORTER_OTLP_HEADERS でヘッダーを追加します。

export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

把握できる主要メトリクス一覧

Claude Code が送出するメトリクスは 8 種類です。

コスト監視の起点は claude_code.cost.usage です。このメトリクスには以下の属性が付くため、モデル別・用途別の詳細なコスト分解が可能です。

• model — 使用モデル(例: claude-sonnet-5)
• query_source — main / subagent / auxiliary
• speed — fast / normal
• effort — low / medium / high / xhigh / max
• agent.name — サブエージェント名
• skill.name — スキル名

claude_code.token.usage には type 属性があり、input / output / cacheRead / cacheCreation を区別できます。キャッシュヒット率を追えるため、CLAUDE.md の最適化効果を数値で確認したい場面にも役立ちます。

バックエンド別の接続設定

OTLP/gRPC 接続(OpenTelemetry Collector 経由)

Grafana や Datadog など OTLP 対応バックエンドへ集約する場合の基本設定です。

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

メトリクスとログで送信先が異なる場合は、個別のエンドポイント変数を使います。

export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.example.com:4318
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4318

Prometheus スクレイプ設定

既存の Prometheus 環境に乗せる場合はエクスポーターを prometheus に切り替えます。

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

prometheus.yml のスクレイプ設定に以下を追加します。デフォルトのスクレイプポートは 8888 です。

scrape_configs:
  - job_name: 'claude-code'
    static_configs:
      - targets: ['localhost:8888']

コンソール出力(動作確認用)

メトリクスの中身をすぐ確認したい場合は console エクスポーターが便利です。

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=5000

チーム・組織向けのカスタム属性設定

複数チームで Claude Code を展開する場合、OTEL_RESOURCE_ATTRIBUTES を使ってメトリクスに部署・コストセンターなどの識別子を付与できます。

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

スペースを含む値はパーセントエンコードが必要です(org.name=John%27s%20Org)。

設定ファイル .claude/settings.json の env セクションにまとめて記述しておくと、チームメンバーが個別に環境変数を設定しなくて済みます。

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer example-token",
    "OTEL_LOG_TOOL_DETAILS": "1",
    "OTEL_RESOURCE_ATTRIBUTES": "department=engineering,team.id=platform"
  }
}

この設定をリポジトリに含めておくと、プロジェクトに参加した全メンバーが自動的に同じ監視設定を使うことになります。

イベントログで把握できること

ログ(イベント)系ではメトリクスより詳細なリクエスト単位の情報が得られます。主なイベント種別は以下のとおりです。

プロンプト内容やツール詳細を記録したい場合は追加の環境変数が必要です。

export OTEL_LOG_USER_PROMPTS=1        # プロンプト文字列を記録
export OTEL_LOG_ASSISTANT_RESPONSES=1 # アシスタント応答テキストを記録
export OTEL_LOG_TOOL_DETAILS=1        # ツールパラメータを記録

これらは機密情報を含む可能性があるため、本番環境への導入はデータ保護の観点から事前に評価してください。SIEM へのセキュリティログ送出も OTel 経由で対応しており、ツール実行の許可・拒否の履歴を外部システムに集約できます。

分散トレース(ベータ)によるボトルネック分析

Claude Code はベータ機能として分散トレースもサポートしています。

export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces

トレースは claude_code.interaction → claude_code.llm_request → claude_code.tool の階層構造で記録されます。サブエージェントの処理も子スパンとして追跡でき、複雑なエージェント処理のどのステップで時間がかかっているかを可視化できます。

カスタムプロキシ経由でトレースコンテキストを伝播したい場合は CLAUDE_CODE_PROPAGATE_TRACEPARENT=1 を追加します。

まとめ

Claude Code の使用量監視は CLAUDE_CODE_ENABLE_TELEMETRY=1 とエクスポーター設定の 2 ステップで始められます。まず console エクスポーターでメトリクスの中身を確認し、既存の Prometheus や Grafana スタックに接続する流れで進めると導入コストを最小に抑えられます。

組織規模での展開では OTEL_RESOURCE_ATTRIBUTES による部署・コストセンター識別と、.claude/settings.json による管理者一元設定を組み合わせると、個別の設定負担なくチーム全体の使用状況を把握できます。個人の費用管理から組織の部署別コスト集計・アラートまで、段階的に監視範囲を広げられるのが OTel 標準に準拠した Claude Code 監視の強みです。