Grafana ダッシュボード作成

ダッシュボードは Grafana に保存される JSON ドキュメントです。すべてのダッシュボードにはパネル、変数、時間範囲、更新設定があります。JSON スキーマを理解することで、API または Grafana Assistant ツールを通じてプログラム的にダッシュボードを作成および変更できます。

---

ダッシュボード JSON 構造

{
  "title": "My Dashboard",
  "uid": "my-dashboard-v1",
  "tags": ["service", "production"],
  "time": { "from": "now-1h", "to": "now" },
  "refresh": "30s",
  "timezone": "browser",
  "schemaVersion": 41,
  "templating": { "list": [] },
  "annotations": { "list": [] },
  "panels": []
}

主要フィールド:

• uid - URL および API 呼び出しで使用される安定識別子。短く意味のあるものにしてください
• schemaVersion - Grafana 11+ では 41 を使用
• time.from / to - 相対形式 (now-1h, now-7d) および絶対 ISO タイムスタンプをサポート
• refresh - 自動更新間隔 ("30s", "1m", "5m", "" でオフ)

---

パネルタイプと使用場面

パネル	ユースケース
Time series	時系列で表示される任意のメトリック。カウンター、レート、ゲージのデフォルト選択肢
Stat	現在の単一値とオプションのスパークライン (例: アップタイム、現在の RPS)
Gauge	最小値/最大値に対するパーセンテージまたは値 (例: ディスク使用率 %)
Bar gauge	複数の値を並べて比較 (例: RPS が高い上位 10 サービス)
Table	マルチカラムデータ (例: ラベル付きアラートリスト)
Heatmap	時系列での分布 (例: リクエスト期間ヒストグラム)
Logs	Loki ログストリーム
Traces	Tempo トレース検索
Text	Markdown ドキュメンテーションパネル
Candlestick	OHLC/金融データ (またはパターン最小値/最大値/平均値)
Node graph	サービス依存グラフ

---

パネル JSON 構造

{
  "id": 1,
  "type": "timeseries",
  "title": "Request Rate",
  "gridPos": { "x": 0, "y": 0, "w": 12, "h": 8 },
  "datasource": { "type": "prometheus", "uid": "${datasource}" },
  "targets": [
    {
      "expr": "sum(rate(http_requests_total{job=\"$job\"}[5m])) by (status_code)",
      "legendFormat": "{{status_code}}",
      "refId": "A"
    }
  ],
  "fieldConfig": {
    "defaults": {
      "unit": "reqps",
      "thresholds": {
        "mode": "absolute",
        "steps": [
          { "color": "green", "value": null },
          { "color": "yellow", "value": 1000 },
          { "color": "red", "value": 5000 }
        ]
      }
    },
    "overrides": []
  },
  "options": {
    "legend": { "calcs": ["mean", "max", "last"], "displayMode": "table", "placement": "bottom" },
    "tooltip": { "mode": "multi", "sort": "desc" }
  }
}

gridPos: ダッシュボードは 24 列グリッドを使用します。一般的な幅: フルウィドス=24、半分=12、3分の1=8、4分の1=6。高さはグリッド単位 (1 単位 ≈ 30px)。

---

便利なユニット識別子

# レート
"reqps"      -- 1 秒あたりのリクエスト数
"ops"        -- 1 秒あたりの操作数
"Bps"        -- 1 秒あたりのバイト数
"percentunit" -- 0.0-1.0 をパーセンテージで表示

# ストレージ
"bytes"      -- バイト数 (KB/MB/GB に自動スケール)
"decbytes"   -- 10 進バイト数 (1 KB = 1000 B)

# 時間
"ms"         -- ミリ秒
"s"          -- 秒
"dtdurationms" -- ミリ秒単位の期間 (「1h 2m 3s」で表示)

# カウント
"short"      -- コンパクト数値 (1.2k, 3.4M)
"none"       -- 生の数値

完全なリスト: Grafana UI の Panel > Field > Unit ドロップダウン、または units reference。

---

テンプレート変数

変数は、ダッシュボードを環境やサービス間で再利用可能にします。

クエリ変数 (メトリックラベルから入力):

{
  "name": "job",
  "type": "query",
  "datasource": { "type": "prometheus", "uid": "prometheus" },
  "query": { "query": "label_values(up, job)", "refId": "A" },
  "refresh": 2,
  "includeAll": true,
  "multi": true,
  "label": "Service"
}

定数変数:

{
  "name": "cluster",
  "type": "constant",
  "query": "production",
  "label": "Cluster"
}

データソース変数 (クエリを編集せずにデータソースを切り替え):

{
  "name": "datasource",
  "type": "datasource",
  "pluginId": "prometheus",
  "includeAll": false,
  "label": "Prometheus"
}

クエリで変数を使用:

# PromQL クエリで変数を参照
rate(http_requests_total{job=~"$job"}[5m])

# マルチ値変数は正規表現 OR を自動的に使用
# $job = ["api", "worker"] の場合、job=~"api|worker" になります

変数をチェーン (2 番目の変数が最初の変数に基づいてフィルター):

{
  "name": "pod",
  "query": "label_values(kube_pod_info{namespace=\"$namespace\"}, pod)"
}

---

変換

変換はクエリ実行後のクライアント側で実行され、クエリを変更せずに結果を再形成します。

一般的な変換:

"transformations": [
  {
    "id": "merge",
    "options": {}
  },
  {
    "id": "organize",
    "options": {
      "renameByName": { "Value #A": "Request Rate", "Value #B": "Error Rate" },
      "excludeByName": { "Time": true }
    }
  },
  {
    "id": "calculateField",
    "options": {
      "alias": "Error %",
      "mode": "reduceRow",
      "reduce": { "reducer": "last" },
      "binary": {
        "left": "errors",
        "right": "total",
        "operator": "/"
      }
    }
  },
  {
    "id": "filterByValue",
    "options": {
      "filters": [{ "fieldName": "Error %", "config": { "id": "greater", "options": { "value": 0.01 } } }],
      "type": "include",
      "match": "any"
    }
  }
]

主要な変換 ID: merge, organize, rename, calculateField, filterByValue, groupBy, sortBy, limit, labelsToFields, seriesToRows, partitionByValues。

---

ダッシュボードリンク

パネルリンク (パネルをクリックしてどこかに移動):

"links": [
  {
    "title": "Go to details",
    "url": "/d/details-dashboard?var-service=${__field.labels.service}",
    "targetBlank": false
  }
]

ダッシュボードリンク (右上隅のリンク):

"links": [
  {
    "title": "Runbook",
    "url": "https://wiki.example.com/runbook/${job}",
    "icon": "external link",
    "targetBlank": true,
    "type": "link"
  }
]

リンク用の組み込み変数:

• ${__value.raw} - 現在のデータポイント値
• ${__field.labels.job} - 現在のシリーズからのラベル値
• ${__url.params} - 現在の URL クエリパラメータ (パススルー)
• ${__from} / ${__to} - Unix ms での現在の時間範囲

---

アノテーション

タイムシリーズパネルにイベントをオーバーレイ表示 (デプロイメント、インシデントなど)。

Loki からのクエリアノテーション:

{
  "datasource": { "type": "loki", "uid": "loki" },
  "expr": "{job=\"deployments\"} |= \"deployed\"",
  "name": "Deployments",
  "iconColor": "blue",
  "titleFormat": "{{service}} deployed",
  "textFormat": "{{version}} by {{author}}"
}

Prometheus からのクエリアノテーション:

{
  "datasource": { "type": "prometheus", "uid": "prometheus" },
  "expr": "changes(kube_deployment_status_observed_generation{namespace=\"production\"}[5m]) > 0",
  "step": "60s",
  "name": "Deployments",
  "iconColor": "blue",
  "titleFormat": "Deploy: {{deployment}}"
}

---

API 経由のダッシュボード

# ダッシュボードを作成または更新
curl -s -X POST \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  "https://myorg.grafana.net/api/dashboards/db" \
  -d '{
    "dashboard": { <dashboard JSON> },
    "folderUid": "my-folder",
    "overwrite": true,
    "message": "Updated via API"
  }'

# UID でダッシュボードを取得
curl -s -H "Authorization: Bearer <API_KEY>" \
  "https://myorg.grafana.net/api/dashboards/uid/my-dashboard-v1" | jq '.dashboard'

# ダッシュボードを検索
curl -s -H "Authorization: Bearer <API_KEY>" \
  "https://myorg.grafana.net/api/search?query=kubernetes&type=dash-db" | \
  jq '.[] | {uid, title, folderTitle}'

# フォルダを作成
curl -s -X POST \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  "https://myorg.grafana.net/api/folders" \
  -d '{"uid": "platform-team", "title": "Platform Team"}'

---

Grafana scenes (app プラグイン)

app プラグインに埋め込まれたダッシュボードの場合は、生の JSON ではなく @grafana/scenes を使用します。 React ベースの scenes API については、grafana-o11y:grafana-scenes スキルを参照してください。

---

参照

• Grafana ダッシュボードドキュメント
• Grafana パネルタイプリファレンス
• Grafana HTTP API — ダッシュボード
• ダッシュボード変数
• 変換リファレンス