--- title: "Claude Code の利用状況を OpenTelemetry で Grafana Cloud に流して手元で確認する" date: 2026-05-31 categories: - "AI IDE" - "Claude Code" - "Grafana" - "o11y" url: "https://hidetaka.dev/ja/writing/dev-notes/send-claude-code-usage-to-grafana" --- Claude Code を一日どれくらい使っているのか、トークンやコストを数字で見たくなりました。調べると OpenTelemetry（OTel）でメトリクスを出せると分かったので、Grafana Cloud に直接流して、手元の Mac で確認できるところまでやってみました。 ## Claude Codeの利用状況はOTelで送信できる Claude Code は OTel 計装を内蔵していて、`CLAUDE_CODE_ENABLE_TELEMETRY=1` を立てて送出先の環境変数を渡すと、メトリクスとイベントログをエクスポートできます。送出先には標準の `OTEL_EXPORTER_OTLP_*` をそのまま読みます。 ## Grafana Cloud 側でトークンと環境変数を出す 最初に送出先の値を Grafana Cloud から取得しましょう。 Grafana Cloud Portal にサインインすると、組織の Overview が開きます。 ![Grafana Cloud Portal の Overview 画面](https://wp-api.wp-kyoto.net/wp-content/uploads/2026/05/b9b64927db20fe48adc85db3792d3a49-20260529215919.png) 少し下にスクロールすると、作成済みのスタックが並んでいます。対象スタックの `Details` を開きます。 ![Grafana Cloud Portal のスタック一覧。対象スタックの Launch / Details ボタン](https://wp-api.wp-kyoto.net/wp-content/uploads/2026/05/2599b74b4a783ed310c285678504ab5f-20260529215939.png) スタックの管理画面（Manage Stack）に `OpenTelemetry / Connect using OTLP protocol` のタイルがあります。ここの `Configure` がメトリクスの送出設定の入り口です。 ![Manage Stack 画面。Grafana / Prometheus / Loki / OpenTelemetry のタイルが並び、OpenTelemetry に Configure ボタンがある](https://wp-api.wp-kyoto.net/wp-content/uploads/2026/05/658001db13ea8baef8346bc526fa8ede-20260529215954.png) `Configure` を開くと、`OTLP Endpoint` が表示されます。東京リージョンのスタックでは次の形でした。 ``` https://otlp-gateway-prod-ap-northeast-0.grafana.net/otlp ``` ![OTLP Endpoint 画面。otlp-gateway-prod-ap-northeast-0.grafana.net/otlp が表示されている](https://wp-api.wp-kyoto.net/wp-content/uploads/2026/05/0c777e8ebe0ec5958b888b084643ed12-20260529231040.png) 同じ画面の `Password / API Token` の `Generate now` を押します。 ![Password / API Token セクション。Generate now のリンク](https://wp-api.wp-kyoto.net/wp-content/uploads/2026/05/8d6cf49b2ef5334a55ad3cab0dd85118-20260529231103.png) `Create an API token` のダイアログが開きます。スコープは `metrics:write` `logs:write` `traces:write` などが既定で付与され、アクセスポリシー名は `stack--otlp-write` の形で自動生成されます。トークン名は任意なので `claude-code` としておくと後で識別しやすいです。 ![Create an API token ダイアログ。トークン名 claude-code、スコープに metrics:write / logs:write / traces:write など](https://wp-api.wp-kyoto.net/wp-content/uploads/2026/05/934dee1164253ae22565dd7ef99dc519-20260529231119.png) トークンを発行すると、画面下に `Environment Variables` のブロックが出ます。ここが目的地で、次のような3行が生成済みの状態でコピーできます。 ``` export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf" export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp-gateway-prod-ap-northeast-0.grafana.net/otlp" # Python requires "Basic%20" instead of "Basic " export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic " ``` ![生成された Environment Variables のブロック。OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf、ENDPOINT、HEADERS=Authorization=Basic が並ぶ](https://wp-api.wp-kyoto.net/wp-content/uploads/2026/05/e45d2d774d72b3c042a92e35e6c05706-20260529231850.png) `HEADERS` に入るのは `glc_` で始まる生のトークンではありません。Basic 認証なので、`Instance ID` を username、`glc_` トークンを password として `InstanceID:token` を base64 した文字列が `Basic` の後ろに入ります。この base64 化を画面がやってくれるので、生成された `OTEL_EXPORTER_OTLP_HEADERS` の行をそのまま貼れば済みます。 ## Mac の全シェルセッションに効かせて走らせる 環境変数を毎回手で打つのは面倒なので、新しいタブでも自動で効くようにします。 今回はトークンを含む値とそれ以外を分けて配置しました。トークンを `.zshenv` に直書きすると dotfiles を公開・git 管理したときに漏れるので、その2行だけ別ファイルに隔離するのが安全です。 まずトークン入りの値を、git 管理外の場所に隔離します。 ``` mkdir -p ~/.config/claude cat > ~/.config/claude/otel.env <<'EOF' export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp-gateway-prod-ap-northeast-0.grafana.net/otlp" export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic " EOF chmod 600 ~/.config/claude/otel.env ``` 次に `.zshenv` に設定の本体と、隔離ファイルの読み込みだけを書きます。`.zshenv` は zsh が起動するたびに読まれるので、インタラクティブシェルでもログインシェルでも効きます。 ``` cat >> ~/.zshenv <<'EOF' # Claude Code -> Grafana Cloud OTLP 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_METRICS_TEMPORALITY_PREFERENCE=cumulative [ -f ~/.config/claude/otel.env ] && source ~/.config/claude/otel.env EOF ``` ここで Claude Code 固有の指定が2つあります。`OTEL_EXPORTER_OTLP_PROTOCOL` を `http/protobuf` にしているのは、Grafana Cloud のゲートウェイが `https://.../otlp` の HTTP エンドポイントだからです。公式クイックスタートにある `grpc` と `localhost:4317` は自前 Collector 向けの値で、Grafana Cloud には通りません。`OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=cumulative` は、Claude Code のメトリクスが既定で delta temporality のためです。Grafana Cloud のメトリクスは Prometheus / Mimir ベースで cumulative を前提とするので、ここを delta のままにするとカウンタ系が期待通りに積み上がりません。 反映と確認をして、1セッション流します。 ``` source ~/.zshenv echo $CLAUDE_CODE_ENABLE_TELEMETRY # 1 echo $OTEL_EXPORTER_OTLP_ENDPOINT # gateway URL echo ${OTEL_EXPORTER_OTLP_HEADERS:0:20} # "Authorization=Basic " まで見えれば OK claude -p "say hello" # 1 セッション分のメトリクスが出る ``` メトリクスは既定で60秒間隔のまとめて送出になるので、流した分が反映されるまで1〜2分待ちます。 ## Grafana の Explore でデータを見る Grafana を開いて `Explore` に入り、データソースを選びます。Grafana Cloud では `Prometheus`種別の、`grafanacloud--prom`を見つけましょう。これがメトリクスの取り込み先です。 ![Explore のデータソース選択。grafanacloud--prom（種別 Prometheus、default バッジ）が先頭にある](https://wp-api.wp-kyoto.net/wp-content/uploads/2026/05/4cbdbca0c807403b48af759313b70c57-20260529232640.png) `grafanacloud--prom` を選んでメトリクスを開くと、候補に次の名前が出ました。 - `claude_code_session_count_total` - `claude_code_token_usage_tokens_total` - `claude_code_cost_usage_USD_total` ![メトリクス選択。claude_code_cost_usage_USD_total、claude_code_session_count_total、claude_code_token_usage_tokens_total が候補に並ぶ](https://wp-api.wp-kyoto.net/wp-content/uploads/2026/05/dbcc03d24015fb3021b756c8f18ed89c-20260529232651.png) 公式ドキュメントの表記は `claude_code.session.count` や `claude_code.cost.usage` です。OTLP から Prometheus に取り込まれる過程で、ドットがアンダースコアに変わり、単位（`tokens` / `USD`）と `_total` が付きます。公式の名前でクエリすると空振りするので、メトリクスブラウザで実際の名前を確認するのが確実です。 ![クエリビルダーで claude_code_session_count_total を選択した状態](https://wp-api.wp-kyoto.net/wp-content/uploads/2026/05/7d72797aef47339428d348916044397c-20260529232741.png) `claude_code_session_count_total` を実行すると、値が `1` で返ってきました。ラベルには `service_name="claude-code"`、`service_version`、`start_type="fresh"`、`terminal_type="Apple_Terminal"`、`session_id`、`user_email` などが付いています。これで送出から取り込み、クエリでの取得までが確認できました。 ![claude_code_session_count_total の結果。値 1 のデータ点と、service_name=claude-code などのラベルが表示されている](https://wp-api.wp-kyoto.net/wp-content/uploads/2026/05/1e397aaa3975ba678ced3631e7ff78c6-20260529232758.png) イベントログ側を見るなら、Explore のデータソースを Loki 系（`grafanacloud--logs`）に切り替えて `{service_name="claude-code"}` で引けます。 ## まとめ Claude Code の OTel 出力を Grafana Cloud の OTLP gateway に直送するだけで、session / token / cost が手元の Explore で見えるようになりました。 要点は、Grafana Cloud の Configure 画面が生成する完成形の環境変数をそのまま使うこと、Claude Code 側で `http/protobuf` と `cumulative` を指定することです。 取り込みができたので、あとはどんな可視化ができるかを挑戦してみようと思います。