Claude Code の Monitoring 機能を触ってみる

OpenTelemetry AI

こんにちは。Legalscape の古矢です。

本記事では Claude Code の OpenTelemetry (OTel) ログやその計測結果を眺めてみたときの雑感を簡単にご紹介したいと思います。 本記事での Claude Code のバージョンは 2.1.84 です。

Claude Code の Monitoring 機能について

Claude Code には OTel を通じてテレメトリデータをエクスポートする機能が組み込まれています。環境変数を設定するだけで、トークン消費量・コスト・ツール実行履歴などのデータを任意の OTel 対応バックエンドに送信できます。

code.claude.com

Anthropic からは ROI 計測のガイドも提供されています。テレメトリの設定方法から Prometheus + Grafana の構築、生産性指標の算出方法まで一通りカバーされており、チームでの活用を見据えた内容になっています。

ローカルでお試し

ROI 計測のガイド の Docker Compose 構成を参考にして、ローカルで下記の環境を立ててみました。

graph LR
  CC["Claude Code"]

  subgraph Docker["Docker Compose ネットワーク"]
    OC["Otel Collector"]
    P["Prometheus<br/>(メトリクス収集)"]
    L["Loki<br/>(ログ収集)"]
    G["Grafana<br/>(可視化UI)"]
  end

  CC -- "metrics + logs" --> OC
  OC -- "metrics" --> P
  OC -- "logs" --> L
  P -- "PromQL" --> G
  L -- "LogQL" --> G

Claude Code がメトリクスとログをプッシュし、OTel Collector がそれぞれ Prometheus（メトリクス）と Loki（ログ）に振り分けます。Grafana は両方のデータソースを参照して可視化を行うビューアの役割です。

Grafana で metrics / logs を見てみる

初めに metrics です。

一点気になった点としては、cache:Read に使用しているトークン数が9割以上を占めていたことです。 キャッシュは読み込みが多く行われるほど効率が良いキャッシュと言えるので、簡単に考えると cacheRead / cacheCreation が定量的な指標として考えられそうです。今回私が数日間のログを流し計測した結果、約 20 となりました。これが良いのか悪いのかは、正直なところ単体では判断がつきません。組織的に集計して、メンバー間やプロジェクト間で比較して初めて意味を持つ数字でしょう。

キャッシュの仕組みの詳細は以下のドキュメントに記載されています。

platform.claude.com

次に、logs を眺めてみます。

一点気になった点としては、Subagent を呼び出した場合に Subagent が行ったイベントのテレメトリを取得できるのかについてですが、実際に値を確認したところ、現状そのようなテレメトリは出力されました。

確認の手順はシンプルで、Claude に Subagent 起動指示をし、その際に出力された OTel ログを確認したという流れになります。例えば今回はコードベースの検索を指示してみます。その結果、以下のイベント群が得られました。seq は event_sequence （セッション内のイベントを順序付けするための単調増加カウンター）を表します。

seq:109  user_prompt                           ← ユーザー入力
seq:110  tool_decision (Agent)                 ← 親: Agent ツール起動許可
seq:111  api_request   model: opus             ← 親: API 呼び出し

--- subagent (Explore / Haiku) 内部 ---
seq:112  tool_decision (Bash)
(略)
seq:132  api_request   model: haiku
--- subagent 内部ここまで ---

seq:133  tool_result   (Agent)                 ← Subagent 完了
seq:134  api_request   model: opus             ← 親に復帰

seq:109 から 111 では model は opus ですが、seq:112 から 132 の間にある全ての api_request イベントは model が haiku でした。コードベースの検索には Haiku が用いられることを踏まえると、Subagent の実行範囲をログから特定できそうなことがわかります。しかし、それ以外に Subagent を識別できそうなフィールドは、確認する限りでは見当たりませんでした。 「特定できそう」と言って断定をしていないのは以下のためです。

  • tool_decision や tool_result イベントはmodel フィールド自体が存在しないため、Subagent が実行したかどうか確定できない
  • 親セッションと Subagent が同じモデルを使った場合（model: inherit など）では区別が不可能

Subagent のテレメトリ改善については Claude Code の GitHub Issue（#14784、#11320、#16424 など）でも報告されています。Hook イベントには v2.1.69 で agent_id / agent_type が追加されましたが、OTel テレメトリ側はまだ未対応のようです。

おわりに

今回は Claude Code の Monitoring 機能を試してみました。

Claude Code 公式ドキュメントの Best Practices には「Develop your intuition」というセクションがあり、こう書かれています。

The patterns in this guide aren't set in stone. They're starting points that work well in general, but might not be optimal for every situation.

このガイドで紹介するパターンは絶対的なものではありません。これらはあくまで出発点であり、一般的にはうまく機能しますが、あらゆる状況において最適とは限りません。

ガイドが絶対的でないからこそ、自分たちのデータからベストプラクティスを見い出すという営みにも価値が生まれるのだと思いました。 まずは簡単な計測から始めてみるだけでも何かしらの洞察が得られるのではないでしょうか。