grafana-dashboards

grafana-dashboards スキルの概要

grafana-dashboards でできること

grafana-dashboards スキルは、オブザーバビリティ用途の本番運用向け Grafana ダッシュボードを、エージェントが設計・下書きできるようにするためのスキルです。
「API の健全性を見たい」「インフラの逼迫状況を追いたい」といった監視目的を、曖昧な指示や汎用的なグラフ案で終わらせず、パネル構成・メトリクスのグルーピング・レイアウト優先度まで含めた、筋のよいダッシュボード設計に落とし込みやすくなります。

grafana-dashboards を使うべき人

このスキルは、Prometheus 系メトリクスを前提に Grafana ダッシュボードを作るプラットフォームエンジニア、SRE、DevOps チーム、バックエンドエンジニア、テックリードに特に向いています。
とくに「どのシステムを観測したいか」は分かっているものの、定番の監視パターンに沿って、より整理されたダッシュボード設計にしたい場合に有効です。

本当に解決したい仕事

多くの利用者が欲しいのは、抽象的な意味での「ダッシュボード」ではありません。障害対応、レビュー、日常的なヘルスチェックの場面で、運用担当者が素早く答えを出せるダッシュボードです。
grafana-dashboards スキルの価値は、メトリクスを単に並べるのではなく、運用判断に沿って整理できる点にあります。つまり「何が壊れているのか」「どれくらい深刻か」「次にどこを見るべきか」「悪化しているのか」といった問いに答えやすくなります。

このスキルが他と違う点

grafana-dashboards の最大の差別化ポイントは、単なる UI 生成ではなく、オブザーバビリティの設計原則に基づいてダッシュボードを組み立てることです。ソースでは主に次の観点が重視されています。

• 情報の階層構造
• サービス向けの RED メソッド
• インフラやリソース向けの USE メソッド

そのため、単に JSON を出すだけの「Grafana ダッシュボードを作って」という汎用プロンプトよりも、実際に使えるレイアウトやパネル選定を重視したい場面で役立ちます。

含まれていないように見えるもの

このスキルは軽量です。リポジトリ上の情報を見る限り、主なガイダンスは SKILL.md にあり、補助スクリプト・ルールファイル・サポート用アセットは含まれていないようです。
つまり grafana-dashboards は、完全なダッシュボード自動構築ツールキットというより、プロンプト設計とダッシュボード設計の土台として使うのが適しています。

grafana-dashboards スキルの使い方

grafana-dashboards の導入コンテキスト

利用中の skills ランタイムがリポジトリからスキルを追加できるなら、wshobson/agents リポジトリから導入し、オブザーバビリティ中心のワークフローで grafana-dashboards スキルを呼び出します。よくある導入パターンは次のとおりです。

npx skills add https://github.com/wshobson/agents --skill grafana-dashboards

環境によってはリポジトリ全体を読み込んだり、別の方法でスキルを同期したりすることもありますが、重要なのはエージェントが次の場所にアクセスできることです。

plugins/observability-monitoring/skills/grafana-dashboards

最初に読むべきファイル

まず確認したいのは次のファイルです。

• plugins/observability-monitoring/skills/grafana-dashboards/SKILL.md

このスキルには強く紐づいた補助ファイルが見当たらないため、有用なガイダンスの大半はここに集約されていると考えてよさそうです。すぐ使い始めやすい一方で、ダッシュボードのスキーマ規約、データソースの詳細、export/import の運用フローは自前で補う前提になります。

grafana-dashboards に渡すべき入力

grafana-dashboards スキルは、ダッシュボードのタイトルだけでなく、運用文脈を渡したときに最も力を発揮します。エージェントには次の情報を与えてください。

• 監視対象のシステム
• ダッシュボードの利用者
• データソースとメトリクス命名規則
• 重要な障害モード
• 想定する時間軸と更新頻度
• サービス視点、インフラ視点、SLO 視点、ビジネス KPI 視点のどれを求めるか

これらがない場合でも構成案は出せますが、パネル定義はかなり汎用的になりやすいです。

grafana-dashboards が最もハマる依頼

grafana-dashboards は、たとえば次のような依頼に向いています。

• API やマイクロサービスの健全性ダッシュボード
• Prometheus を前提にした RED ダッシュボード
• USE を使ったインフラダッシュボード
• SLO やレイテンシ中心のオブザーバビリティボード
• ドリルダウン用セクションを備えた本番運用の概要ダッシュボード

一方で、単発のアドホックな可視化、カスタムプラグイン依存の強い Grafana 作業、あるいはダッシュボード構造よりもデータソース固有のクエリ言語の正確さが重要な環境には、そこまで向いていません。

雑な依頼を強いプロンプトに変える

弱いプロンプト:

• “Create a Grafana dashboard for my app.”

よりよいプロンプト:

• “Use the grafana-dashboards skill to design a production Grafana dashboard for a customer-facing API. Datasource is Prometheus. Focus on RED metrics, 30s refresh, last 6h by default, and an on-call audience. Include top-row stat panels for traffic, error rate, p95 latency, and saturation signals. Then propose panel titles, layout order, and example PromQL queries.”

これが機能する理由:

• 監視対象のシステムが明示されている
• 設計手法が指定されている
• 想定ユーザーと時間範囲が決まっている
• 構造とクエリの両方を求めている
• 汎用的な出力に流れないだけの制約がある

grafana-dashboards 用プロンプトテンプレート

次のテンプレートをそのまま調整して使えます。

• “Use the grafana-dashboards skill to design a Grafana dashboard for [service/system].
• Audience: [on-call / engineering managers / platform team]
• Datasource: [Prometheus / other]
• Dashboard goal: [incident response / daily health review / SLO tracking]
• Key metrics: [request rate, error rate, p95 latency, CPU saturation, queue depth]
• Default time range: [1h / 6h / 24h]
• Refresh interval: [15s / 30s / 1m]
• Constraints: [must fit single screen / include variables / separate business KPIs from infra]
• Output wanted: [panel plan / Grafana JSON draft / PromQL suggestions / layout rationale]”

grafana-dashboards の実践ワークフロー

grafana-dashboards を実務で使うなら、次の流れが安定します。

1. ダッシュボードの目的を 1 文で定義する。
2. RED、USE、SLO、KPI 重視のどれで見るか決める。
3. データソース上で実際に使えるメトリクスを列挙する。
4. まずエージェントにパネル階層を考えさせる。
5. 次にサンプルクエリを出させる。
6. 実際のラベル名やメトリクス名に照らして不足を洗い出す。
7. その後で初めて Grafana JSON や provisioning 向け出力を求める。

この順番にすると、メトリクスモデルを検証する前に、見た目だけ整った実用性の低いダッシュボード JSON を生成してしまう、よくある失敗を避けやすくなります。

grafana-dashboards が示す設計パターン

ソースには、実務で残す価値のある設計パターンがいくつか明確に出ています。

• 重要なメトリクスは大きな数値表示や stat パネルで先頭に置く
• 傾向を追う部分には time series を使う
• 詳細な診断系パネルはダッシュボード下部に回す
• サービス挙動には RED を使う
• ホスト、ノード、ディスク、キューなどのリソースには USE を使う

オブザーバビリティチームにとって、grafana-dashboards の本当の価値は、グラフ数を増やすことではなく、意思決定の流れを改善できることにあります。

出力として期待できるもの

リポジトリの内容からすると、このスキルで得られそうなのは主に次のような成果物です。

• ダッシュボードのセクション設計
• パネルの並び順に関する提案
• メトリクス分類の提案
• JSON 風のダッシュボード例
• 監視手法に基づくパネル選定

ただし、実環境のラベル、recording rule、フォルダ構成、権限設定、Grafana provisioning 設定まで、何も渡さずに正確に仕上がるとは考えないほうが安全です。必要なら、その情報を明示的に与える必要があります。

出力品質を変える実践的なコツ

grafana-dashboards をうまく使うには、少なくとも次の情報を毎回含めるのがおすすめです。

• 実在するメトリクス名
• パーセンタイルが使えるかどうか
• cardinality 上の制約
• cluster、namespace、service のような環境フィルタ
• 概要把握用のダッシュボードなのか、深掘りデバッグ用なのか

これらの情報があるかないかで、トップパネルの有用性、変数設計の現実味、クエリのスコープ設定が大きく変わります。

grafana-dashboards スキル FAQ

grafana-dashboards は初心者にも向いていますか？

はい。Grafana とメトリクスの基本をすでに理解しているなら有用です。grafana-dashboards スキルは、「何を先に見せるべきか」「どうパネルをグルーピングするか」の骨組みを与えてくれます。
一方で、Prometheus の基礎、Grafana provisioning、クエリ言語の基本まで含めた初心者向けチュートリアルとしては弱めです。

grafana-dashboards は実際の Grafana JSON を作れますか？

JSON 形式に近い出力のガイドや下書きは可能ですが、結果はあくまでたたき台として扱うべきです。最終的には、自分の環境でパネルタイプ、datasource UID、クエリ構文、変数、Grafana のバージョン互換性を確認する必要があります。

普通のプロンプトより grafana-dashboards のほうが良いですか？

オブザーバビリティ用途なら、多くの場合は yes です。grafana-dashboards の価値は、RED、USE、情報階層といった実績あるダッシュボード設計パターンに、エージェントの出力を寄せられることにあります。
汎用プロンプトだと、見た目は賑やかでも、運用現場で素早く読めないダッシュボードになりがちです。

どんなときは grafana-dashboards を使わないほうがいいですか？

次のような課題が中心なら、grafana-dashboards は外したほうがよい場合があります。

• 壊れた PromQL の修正
• Grafana provisioning パイプラインの管理
• カスタムパネルやプラグインの構築
• export 済みダッシュボードの解析
• 標準的なオブザーバビリティ設計より、データソース固有の癖への対応が主題になっているケース

こうした場合は、より専門特化したスキル、あるいは対象リポジトリに直接寄せたプロンプトのほうが適していることが多いです。

grafana-dashboards は Prometheus 専用ですか？

いいえ。ただし、Prometheus 的なオブザーバビリティの考え方とは最も相性が良いです。別のデータソースを使う場合は、クエリ言語、利用可能なパネル種別、フィールド名を明確に伝えて、PromQL 前提で話が進まないようにしてください。

grafana-dashboards は Observability チーム専用ですか？

いいえ。構造化された運用可視性が目的であれば、ビジネス KPI やサービス健全性のダッシュボードを必要とするプロダクトチームや開発チームにも合います。
ただし、このスキルが最も強いのは、経営レポート的な見た目よりも、監視ロジックが明確なダッシュボードを求める場面です。

grafana-dashboards スキルを改善する方法

まずメトリクス一覧をエージェントに渡す

grafana-dashboards の結果を手早く改善したいなら、ダッシュボード依頼の前に短いメトリクス一覧を渡すのが最も効果的です。実際のメトリクスが 10〜15 個あるだけでも、存在しない名前をエージェントが作ってしまうのを防ぎ、実装可能なパネル設計にかなり寄せられます。

ダッシュボードが答えるべき運用上の問いを明確にする

よいダッシュボードは、グラフの羅列ではなく、問いから生まれます。たとえば次のような問いです。

• “Can on-call tell in 30 seconds whether the API is broken?”
• “Can we detect CPU saturation before latency rises?”
• “Can product and ops review revenue-impacting errors in one view?”

こうした問いがあると、最上段に置くべきものと、下段の診断セクションに回すべきものがはっきりします。

概要パネルとデバッグ用パネルを分ける

grafana-dashboards 利用時によくある失敗は、最初の 1 画面に詰め込みすぎることです。エージェントには、出力を次のように分けるよう依頼してください。

• エグゼクティブ向け、または on-call 向けの要約
• トレンド確認セクション
• ドリルダウンまたは詳細診断セクション

この分け方にすると、プレッシャーの高い状況でも本当に目で追えるダッシュボードになります。

使う手法を明示する

エージェントが自動で適切な監視モデルを選ぶと期待しないほうが安全です。次のように、はっきり指定してください。

• リクエスト駆動のサービスには RED を使う
• コンピュートやインフラには USE を使う
• 顧客向け API では SLO パネルと RED を組み合わせる

この 1 指示だけで、「ベストプラクティスで」と曖昧に頼むより、パネルの妥当性が大きく改善することがよくあります。

出力だけでなく理由も聞く

初稿が一見もっともらしくても汎用的すぎる場合は、次のように追加で聞いてください。

• なぜ各トップパネルがその位置に置かれるべきなのか
• 画面スペースが限られるなら、どのパネルを削るべきか
• どのメトリクスが先行指標で、どれが結果指標なのか

こうすると grafana-dashboards スキルは、見た目だけ整った出力ではなく、説明可能な設計を返しやすくなります。

初稿への修正指示は具体的に出す

反復改善は、フィードバックが具体的なほど機能します。

• “We do not have histogram buckets.”
• “Use namespace and pod variables.”
• “This dashboard is for mobile backend only.”
• “Remove business KPIs; this is strictly incident response.”
• “Keep it to one screen for a NOC display.”

具体的な制約を与えると、2 回目の出力は大きく改善しやすくなります。

弱い出力の典型サインを見逃さない

次のようなドラフトには注意が必要です。

• 手元に存在しない汎用メトリクス名を使っている
• time series より上にテーブルが多すぎる
• サービス観点とインフラ観点が整理されないまま混在している
• 上段の要約が明確でない
• 想定ユーザーやデフォルト時間範囲を無視している

こうした兆候は、スキルの呼び出し時に文脈が足りなかったか、依頼範囲が広すぎたことを示しています。

リポジトリを踏まえて grafana-dashboards を強化する

このスキルは主に SKILL.md に依存しているようなので、実務での成果を高めるには、自分たちのローカル標準と組み合わせるのが有効です。

• 自社の Grafana JSON スキーマ例
• 命名規則
• PromQL スニペット
• フォルダ構成やテンプレート化のルール

実際には、grafana-dashboards は設計の頭脳として使い、実装の細部は自分たちの環境側で補うのが最も強い使い方です。