Claude Codeでどこまでできる？

Claude Codeの使い方や連携を、実際に試してわかりやすく伝えるサイト

Claude CodeのOpenTelemetryを有効にしてPrometheus+Grafanaで可視化する手順

,
CC-071

Claude Codeが裏でどのツールを何回呼び出しているか、セッションごとにどれだけトークンを使っているか――そういう数字、気になりませんか。環境変数を4つ設定するとメトリクスとして出力できるようになり、Docker ComposeでPrometheusとGrafanaを立ち上げればグラフで確認できます。

この記事でやること

次の3つを順番に進めます。

  • Claude CodeのOpenTelemetry機能を有効にする
  • Prometheus + GrafanaをDocker Composeでローカルに立ち上げる
  • Grafanaのダッシュボードでツール呼び出し回数・トークン使用量を確認する

前提としてWindows環境（PowerShell）を使います。Docker Desktopが動いていれば、あとはコピペで進められますので、Dockerをまだ入れていない場合は先にインストールしておいてください。

可視化できると何が嬉しいか

手順に入る前に、「なぜわざわざ可視化するのか」を押さえておきましょう。

一番のメリットは、無駄なトークン消費に気づけることです。たとえばセッションを振り返ると「Readツールを20回も呼んでいた」が見えてきます。同じ情報を探すならGrepで絞り込んだ方が呼び出し回数もトークンも抑えられる——そういう改善の余地が数字で見えてきます。

トークンの消費傾向が分かると、依頼文の書き方も工夫できるようになります。「ファイルを読む前に検索して絞り込んで」と指示するだけで無駄な読み込みが減り、コストが半分近くになった――というケースもありました。Claude Codeに頼むだけで、ブログ記事のタイトル案はどこまで出せる？でも触れていますが、依頼文を工夫することでAIの出力精度や効率は大きく変わります。

セッション全体の傾向をつかめるのも大きいです。「このプロジェクトはファイルが多くてReadが増えがち」「エラー対応のセッションはトークンを使いがち」というパターンが分かると、依頼文を状況に合わせて調整しやすくなります。Claude Codeに頼むだけで、プログラムのエラー修正はどこまでできる？で解説しているように、エラー対応時は特にトークン消費が多くなる傾向があるため、可視化しておくと便利です。

OpenTelemetryって何？——最小限の説明

OpenTelemetryは、アプリの動きを計測してデータとして取り出す仕組みです。「何をどれくらい使っているか」を標準形式で記録・送信する規格と言っていい。

家のメーター（電力量計）をイメージしてください。冷蔵庫がどれだけ電気を使っているか、エアコンを付けっぱなしだとどうなるか――メーターがあれば数字で分かりますよね。OpenTelemetryはClaude Codeにとってのメーターです。何回ツールを呼び出したか、どれだけトークンを使ったか、セッション時間はどれくらいかを計測してくれます。

仕組みの詳細は知らなくても大丈夫です。この記事では「メーターを取り付けて、画面で数字を見る」部分だけをやります。

事前に必要なもの

始める前に、以下が揃っていることを確認してください。

  • Claude Codeがインストール済みであること
  • Docker Desktopがインストール済みで、起動していること（システムトレイにクジラのアイコンがあればOK）
  • Windows 10 または 11（PowerShell前提で進めます）
  • インターネット接続（初回はDockerイメージのダウンロードが入ります）

Docker Desktopを入れていない場合は、先にDocker Desktop for Windowsからインストールして起動しておいてください。DockerはComfyUIをWindowsに導入する際にも必要になるツールなので、この機会に環境を整えておくと他の作業でも役立ちます。

Step 1: Claude Codeでテレメトリを有効にする

Claude Codeは環境変数を4つ設定すると、メトリクスを出力し始めます。

環境変数の設定

設定するのは次の4つ。

  • CLAUDE_CODE_ENABLE_TELEMETRY=1
  • OTEL_METRICS_EXPORTER=otlp
  • OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
  • OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

公式のデフォルトはgRPC + ポート4317ですが、ここではhttp/protobuf + ポート4318を使います。理由はシンプルで、後で使うDocker Composeの構成がhttp/protobufの方が扱いやすいからです。プロトコルとポートを合わせるため、OTEL_EXPORTER_OTLP_PROTOCOL の設定も忘れないようにしてください。

settings.jsonで永続化する

毎回設定するのは手間なので、%USERPROFILE%\.claude\settings.json に書いて永続化します。

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318"
  }
}

すでに settings.json がある場合は、既存のJSONに env キーを追加してください。

PowerShellで一時的に設定する場合

その場だけ試したい場合は、PowerShellで次のように入力します。

$env:CLAUDE_CODE_ENABLE_TELEMETRY = "1"
$env:OTEL_METRICS_EXPORTER = "otlp"
$env:OTEL_EXPORTER_OTLP_PROTOCOL = "http/protobuf"
$env:OTEL_EXPORTER_OTLP_ENDPOINT = "http://localhost:4318"

この場合、PowerShellのウィンドウを閉じると設定も消えます。

補足: OTEL_LOGS_EXPORTERについて

上記の設定はメトリクス（数字のデータ）だけを対象にした最小構成です。ログ（実行の記録詳細）も取りたい場合は、OTEL_LOGS_EXPORTER=otlp を追加で設定します。まずはメトリクスだけでも十分見える化できるので、この記事ではメトリクス専用の構成で進めます。

Step 2: Prometheus + Grafanaを立ち上げる

Claude Codeが出力したメトリクスを受け取るために、PrometheusとGrafanaをDocker Composeで立ち上げます。

docker-compose.yml

作業フォルダ（どこでも構いません）に docker-compose.yml を作成し、次の内容を貼り付けます。

services:
  otel-collector:
    image: otel/opentelemetry-collector-contrib:latest
    ports:
      - "4318:4318"
      - "9464:9464"
    command: ["--config", "/etc/otelcol/config.yaml"]
    volumes:
      - ./otel-collector-config.yaml:/etc/otelcol/config.yaml

  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin

OpenTelemetry Collectorが4318番ポートでメトリクスを受け取り、9464番でPrometheus形式に変換して出力します。

otel-collector-config.yaml

同じフォルダに otel-collector-config.yaml を作成します。

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

exporters:
  prometheus:
    endpoint: 0.0.0.0:9464
    namespace: claude_code
    resource_to_telemetry_conversion:
      enabled: true

service:
  pipelines:
    metrics:
      receivers: [otlp]
      exporters: [prometheus]

prometheus.yml

同じフォルダに prometheus.yml を作成します。

global:
  scrape_interval: 60s

scrape_configs:
  - job_name: "claude-code"
    static_configs:
      - targets: ["otel-collector:9464"]

スクレイピング間隔は60秒にしています。短すぎるとデータが重なるだけで精度も上がりません。

起動する

PowerShellで作業フォルダを開き、次のコマンドを実行します。

docker compose up -d

初回はDockerイメージのダウンロードに数分かかります。完了したら docker compose ps で3つのコンテナが Up になっていることを確認してください。

Step 3: Grafanaでダッシュボードを見る

コンテナが立ち上がったら、Grafanaにアクセスします。

Grafanaにログインする

  1. ブラウザで http://localhost:3000 を開く
  2. ユーザー名 admin、パスワード admin でログインする
  3. パスワード変更を求められたらスキップして構いません

データソースを追加する

  1. 左メニューの「Connections」→「Data sources」を開く
  2. 「Add data source」をクリック
  3. 「Prometheus」を選択
  4. URL欄に http://prometheus:9090 と入力
  5. 画面下部の「Save & test」をクリック
  6. 「Successfully queried the Prometheus data source」と表示されればOK

メトリクスを確認する

データソースが繋がったら、左メニューの「Explore」を開きます。クエリ欄に claude_code_ と入力して候補を確認してみてください。

Claude Codeを一度実行した後であれば、claude_code_ から始まるメトリクス（セッション数やトークン使用量など）が候補に現れます。まだ実行していない段階だと候補が出ないので、先にClaude Codeを立ち上げて適当な操作をしてから、しばらく待って再度確認してください。

ダッシュボードとして保存したい場合は、Explore画面上部の「Add to dashboard」→「New dashboard」で保存できます。

動作確認——ここまでできていればOK

一通り終わったら、次のポイントをチェックしてください。

  • [ ] http://localhost:9464/metrics にアクセスして、claude_code_ で始まる行が表示される
  • [ ] Grafanaのデータソース設定画面で「Save & test」が緑色で通過する
  • [ ] Claude Codeを1回実行した後、GrafanaのExploreで claude_code_ 系のメトリクスが候補に出る

3つともクリアしていれば、可視化の土台は完成しています。

うまくいかない時のトラブルシューティング

メトリクスエンドポイント（9464）にアクセスできない

  • docker compose ps で otel-collector が Up になっているか確認する
  • docker compose logs otel-collector でエラーログが出ていないか確認する
  • ポート4318や9464が別のアプリに使われていないか確認する

Grafanaにデータが表示されない

  • Claude Codeを一度実行してから60秒以上待つ（スクレイピング間隔の分）
  • GrafanaのデータソースURLが http://prometheus:9090 になっているか確認する（localhost ではない点に注意）
  • Prometheus自身の画面 http://localhost:9090 で claude_code_ 系メトリクスを検索してみる。ここに出なければ、PrometheusがCollectorからデータを取れていない

環境変数が反映されているか確認する

Claude Codeのセッション内で echo $env:OTEL_EXPORTER_OTLP_ENDPOINT を実行して、設定値が返ってくるか確認してください。何も返ってこない場合は、settings.json の記述場所が間違っているか、Claude Codeの再起動が必要です。

Docker Composeをやり直す

設定を変えた場合は、次のコマンドで再起動できます。

docker compose down
docker compose up -d

docker compose down でコンテナを止めて削除し、再度立ち上げます。データも消えるので注意してください。

よくある失敗: 再起動忘れ

環境変数を settings.json に書いた後、Claude Codeを再起動し忘れるケースが多いです。設定ファイルを書き換えたら、Claude Codeを一度終了して立ち上げ直してください。

次にやること

ローカルでの可視化が動いたら、次は使い方を広げていく方向で。

  • ダッシュボードのカスタマイズ: Grafanaのパネル編集で、トークン使用量の推移グラフやツール別の呼び出し回数など、見たい指標を自分好みに並べられます。Claude Codeに頼むだけで、WordPress用の記事下書きはどこまで作れる？で紹介しているようなワークフロー自動化と組み合わせると、自分の作業パターンがさらに可視化できます
  • Grafana Cloudへの移行: ローカルでDockerを立ち上げたくない場合は、OTLPエンドポイントをGrafana Cloud向けに変更するだけでクラウド上で同じ可視化ができます。無料枠でも十分に試せます
  • ログの取得: OTEL_LOGS_EXPORTER=otlp を追加で設定すると、メトリクス（数字）だけでなく実行のログ詳細も記録できるようになります。より細かい分析をしたい場合に試してみてください

環境変数4つと docker compose up -d で、Claude Codeの動きが数字で見えるようになりました。まずは数日使ってみて、自分の使い方の傾向がどう見えるか確認してみてください。

まとめ

環境変数4つでClaude Codeのテレメトリが有効になり、Docker ComposeでPrometheusとGrafanaが立ち上がります。トークン使用量やツール呼び出し回数がグラフで確認できるので、まずは動かして自分の使い方の傾向を見てみてください。

Claude Code 関連記事