Claude CodeでGrafanaの変数設計を見直す — $__rate_intervalとAllの落とし穴

Grafanaのテンプレート変数は、ダッシュボードのクエリやタイトルに差し込む「値の置き場」です。サーバー名やジョブ名を変数にすれば、1枚のダッシュボードで複数の対象を切り替えられます。ただ、変数が増えるほど、[5m] の固定値や = と =~ の取り違え、Allを選んだ途端に空になるパネルといった設計ミスが入り込みます。

こうした点検は、ダッシュボードのJSONをリポジトリに置いておけば、Claude Codeに任せやすい作業です。この記事では、Prometheusを例に、Claude Codeへ何を読ませ、どの観点で見直させるかを順に見ていきます。

先にダッシュボードJSONをリポジトリへ置く

Claude Codeが読めるのは、手元のファイルです。画面上で作ったダッシュボードは、そのままでは点検対象になりません。

Grafanaには、設定ファイルでデータソースやダッシュボードを定義するプロビジョニングの仕組みがあります。provisioning/dashboards ディレクトリに置いたYAMLの providers から、ローカルのパスにあるダッシュボードJSONを読み込めます。この形にしておくと、変更をGitで追え、Claude Codeにも @ で渡せます。JSONを置かず、MCP経由でGrafanaから直接読む方法もあります（導入とRBAC設計、ダッシュボードJSONの読み方）。

変更前に提案だけ見たいときは、プランモードで起動します。

claude --permission-mode plan

プランモードのClaude Codeは、ファイルを読んで計画を示すだけで、承認するまで編集しません。ステータスバーに ⏸ plan mode on と出ているあいだは、JSONに手が入りません。変数まわりの修正は、1か所の書き換えが全パネルに波及するので、先に差分の方針を見られるほうが安全です。

JSONを渡すときは、@dashboards/node-overview.json のように書きます。ファイルがツールの読み取り上限（既定で25,000トークン）に収まれば内容がそのまま会話に入ります。大きなダッシュボードは超えやすいので、点検したい変数やパネルの範囲を指定して依頼するほうが確実です。

$__rate_intervalを軸に、時間幅の指定を洗う

最初に見るのは、rate() や increase() の範囲指定です。ここは3通りの書き方が混在しやすい箇所です。

$__rate_interval は、Prometheusデータソース向けのGrafana独自の変数です。rate() と increase() で使う前提で、窓が少なくともスクレイプ4回分を覆うよう計算されます。p95・p99の出し方はmcp-grafanaでPromQLを実行する手順で扱っています。計算式は次のとおりです。

max($__interval + scrape_interval, 4 * scrape_interval)

$__interval はGrafanaが「時間範囲 ÷ 解像度」から自動で出す間隔で、1時間表示のフルスクリーンなら2分程度、6か月表示なら1日程度になります。scrape_interval はクエリごとのMin stepがあればそれ、なければデータソースのScrape interval設定が使われます。

点検の入口として、まず固定値と $__interval の使用箇所を洗い出させます。

claude -p "dashboards/ 配下のJSONから、rate() と increase() の範囲指定が \
[\$__rate_interval] 以外のクエリを、ファイル名・パネル名・式の3列の表にして" \
  --allowedTools "Read"

--allowedTools "Read" だけを許可しているので、この実行ではファイルを読むだけです。出てきた表を見て、直すクエリを決めてから編集に進みます。

直す前に確かめたい3つの前提

$__rate_interval に置き換えれば終わり、ではありません。Prometheusのテンプレート変数には、次の落とし穴があります。

• データソースのScrape intervalが既定の15秒のまま、実際のスクレイプが60秒だと、窓が短すぎて rate() が空になる
• 編集画面ではパネルが全幅なので、ダッシュボード上で幅が狭くなると $__interval が大きくなり、見え方が変わる
• レコーディングルールのクエリには $__rate_interval を使わず、[5m] のような固定値を使う

三つ目は、置き換えの対象から外す例外です。ダッシュボードのJSONにレコーディングルール用の式が混ざっていることは少ないものの、Claude Codeへの依頼には「固定値のままにする式は理由を添えて残す」と書いておくと、機械的な全置換を避けられます。Scrape intervalの実際の値は、Prometheusの設定ファイルとデータソース設定を突き合わせて確認します。

Allと複数選択は「=~」とセットで直す

次に見るのは、複数選択とAllを有効にした変数です。この2つのどちらかを有効にすると、変数の値は value1|value2 のような正規表現として展開されます。そのため、ラベルの一致は = ではなく =~ で書く必要があります。

# 見直し前: 複数選択やAllのとき、正規表現として扱われない
rate(http_requests_total{job="$job"}[5m])
 
# 見直し後
rate(http_requests_total{job=~"$job"}[$__rate_interval])

$job を = のまま使うパネルは、1件だけ選んでいるあいだは動くので、見落とされがちです。Allを選んだときに初めて空になります。Claude Codeには「複数選択かAllが有効な変数を使うセレクタで、= のものを列挙して」と頼むと、変数の定義とパネルのクエリを突き合わせて拾えます。

Custom all valueの扱い

Allの既定の展開は、全オプションを連ねた長い式です。値が多いと式が長くなり、性能の問題が出ることがあります。この場合はCustom all valueに .+ のような正規表現を入れ、Allを「何にでも一致する」に置き換える手があります。

注意点が2つあります。

1. Custom all valueはエスケープされず、そのままデータソースに渡ります。データソースにとって有効な値を自分で書く必要があります
2. 空欄でなければ、複数選択時の連結形式（value1,value2,value3）にならず、* や all のような指定値になります

また、変数の既定値を「空」にしたいときの回避策として、Include Allを有効にしてCustom all valueに .+ を入れる方法があります。変数に既定値の概念がなく、先頭の値が自動選択されるためです。

Query変数のチェーンは段数と順序を見る

Query変数のクエリに別の変数を含めると、チェーン（連鎖）変数になります。region > cluster > namespace > pod のように、上位の選択で下位の候補が絞られる構成です。

仕組みは単純です。たとえば server 変数のクエリが $datacenter.* なら、datacenter でAを選ぶと A.*、AとBを選ぶと {A,B}.* に展開されます。段数に技術的な上限はありませんが、段が増えるほどクエリ負荷が上がります。ルート変数を変えると、依存する変数すべてのクエリが走り終えてから、パネルが更新されるためです。

点検では次の3点を見ます。

• 並び順: 依存のない変数を上に、子は親の下に置く。画面上に依存関係の表示はなく、並び順だけが手がかりになる
• 段数: 4段（国・地域・サーバー・メトリクス）のような構成は、ルートを切り替えるたびに4回分のクエリが走る
• 固定できる段: 変化しないサーバー名やリージョン名は、Query変数ではなくCustom変数にすると、更新時のクエリ数が減る

Prometheusでは、Query変数のRefreshに On dashboard load と On time range change があります。$__range に依存する変数は後者にします。ただし、label_values を使うClassic queryは $__range などの組み込み変数に対応しません。その場合は query_result() を使い、query_result(max_over_time(up{job="$job"}[${__range_s}s]) == 1) のように書きます。

Claude Codeには、JSONの templating 配下にある変数の定義を順に読ませ、依存関係のグラフを書き出させるのが向いています。出力は目視確認の補助です。実際の依存は、Grafana上で上位の値を切り替えて下位の候補が変わるかを確かめます。

Repeatは複数選択変数の値の数に引きずられる

パネルや行のRepeatは、複数選択変数の値ごとにパネルを増やします。Repeat by variableにその変数を指定し、方向を横か縦から選びます。横を選ぶと、1行に並ぶ最大数を指定でき、ほかのパネルを同じ行には置けません。

設計上の注意は、Allとの組み合わせです。Allは全値の選択を意味するので、候補が100件ある変数でRepeatすると、パネルも100枚並ぶことになります。値の数が増えうる変数でRepeatを使うなら、次の対策を点検項目に入れます。

• Repeat対象の変数は候補数が限られる変数（環境名やリージョンなど）に絞る
• 行の見出しにも変数名を入れて、どの値の行かを分かるようにする
• Allを使わない設計なら、Include Allを外す

Claude Codeへの依頼文と、CLAUDE.mdに書く規約

ここまでの観点を、そのまま依頼文にします。プランモードで次のように頼むと、提案を差分の単位で確認できます。

@dashboards/node-overview.json の templating と各パネルのクエリを点検して。
観点は4つ。
1. rate()/increase() の範囲が [$__rate_interval] か。固定値のままにするなら理由を添える
2. 複数選択かIncludeAllが有効な変数を、= で使っているセレクタ
3. Query変数の依存順と段数
4. Repeat対象の変数が増えたときのパネル数
まず問題の一覧だけ出して、修正はその後に1観点ずつ。

「問題の一覧、修正は1観点ずつ」と分けるのは、レビューを小さくするためです。変数の変更はJSON全体に散るので、観点ごとにコミットを分けておくと、戻したいときに切り分けられます。

繰り返し使う規約は、プロジェクトの CLAUDE.md に書いておきます。ファイルの断片は例えば次のような形です。

## Grafanaダッシュボードの変数
- rate()/increase() の範囲は [$__rate_interval] を使う。レコーディングルールだけ固定値
- 複数選択かIncludeAllの変数は =~ で使う
- 変数のチェーンは3段まで。変化しない値はCustom変数にする
- 変数の並びは、依存のない変数を上、子は親の直下にする

CLAUDE.md は、書いた内容が毎回のセッションの前提になります。ダッシュボードを触るたびに観点を打ち直さずに済みます。ここに書く段数の上限（3段）は、運用上の目安として置いた例です。Grafana側に上限の定めがあるわけではありません。

修正の後はGrafanaの画面で確かめる

JSONの書き換えが正しいかは、Claude Codeの説明ではなく、Grafanaの動きで判断します。次の3点を実際の画面で見ます。

1. 時間範囲を1時間と30日で切り替えて、$__rate_interval のパネルが空にならないか
2. 複数選択の変数でAllを選び、=~ に直したパネルに値が出るか
3. チェーンの親を切り替えて、子の候補が入れ替わるか

どれかで空になったときは、まずデータソースのScrape intervalと、Prometheusの実際の設定が一致しているかを疑います。

まとめ

変数の見直しは、「時間幅」「All」「チェーン」「Repeat」の4観点に分けると進めやすくなります。$__rate_interval への置き換えは、データソースのScrape intervalを実環境と合わせてから行うのが前提で、Allを使う変数は =~ とセットで直します。Claude Codeには一覧の作成と一括の下書きを任せ、空にならないかの判断はGrafanaの画面で行う、という分担が現実的です。