Grafana 操作マニュアル

Grafana はデータ可視化プラットフォームです。主要な概念は以下の通りです: データソース (datasource)、ダッシュボード (dashboard)、パネル (panel)、アラートルール (alert rule)、コンタクトポイント (contact point)、プロビジョニング (provisioning)。

プロビジョニング

Grafana はファイルを通じてダッシュボードとアラートルールを自動的に作成できます。UI で手動操作する必要はありません。ファイル変更後、約 10 秒で自動的に反映されます。systemctl reload grafana で強制リフレッシュできます。

/etc/grafana/provisioning/
├── dashboards/
│   ├── host-provider.yaml              # プロバイダー設定: どのフォルダから JSON を読むか
│   └── json-all/host/*.json            # ダッシュボード JSON ファイル
├── alerting/
│   └── rules.yaml                      # アラートルール (datasourceUid を含む)
└── datasources/
    └── prometheus.yaml                 # データソース定義

プロバイダーの YAML:

apiVersion: 1
providers:
- name: host
  folder: 主机状态                       # 対象フォルダ (存在しない場合は作成)
  type: file
  options:
    path: /etc/grafana/provisioning/dashboards/json-all/host

データソースの YAML:

apiVersion: 1
datasources:
- name: Prometheus
  type: prometheus
  url: http://localhost:9090
  access: proxy
  uid: dfguyfutpcnpca                   # 固定 UID (ダッシュボード JSON で参照)

ダッシュボード JSON のデバッグ

# ダッシュボードのデータソースとパネルを表示
jq '.panels[] | {title, targets: .targets[].expr}' dashboard.json

# テンプレート変数を表示
jq '.templating.list[] | {name, query, current}' dashboard.json

# データソース UID を一括置換
sed -i 's/"uid": "old-uid"/"uid": "new-uid"/g' dashboard.json

Unified Storage 操作 (Grafana 12 以降)

Grafana 12 では、SQLite を使用してすべてのオブジェクト (unified storage) を保存します。UI で作成したダッシュボードはファイルではなくデータベースに保存されます。

systemctl stop grafana
cp /var/lib/grafana/grafana.db grafana.db.bak   # まずバックアップ!

sqlite3 /var/lib/grafana/grafana.db <<SQL
-- UI で作成したダッシュボードとフォルダを表示
SELECT name, kind FROM resource WHERE kind IN ('dashboard', 'folder');

-- UI で作成したダッシュボードを削除 (プロビジョニングされたものはファイルで管理されるため、ここには含まれません)
DELETE FROM resource WHERE name = 'old-dashboard' AND kind = 'dashboard';
DELETE FROM resource_history WHERE name = 'old-dashboard';

-- 履歴テーブルをクリーンアップ (容量が大きくなる可能性があります)
SELECT COUNT(*) FROM resource_history;
DELETE FROM resource_history;
SQL

systemctl start grafana

アラート

# コンタクトポイントの一覧表示
curl -s -u admin:<pass> http://localhost:3000/api/v1/provisioning/contact-points | jq

# 秘密鍵を含むコンタクトポイントをエクスポート
curl -s -u admin:<pass> 'http://localhost:3000/api/v1/provisioning/contact-points/export?decrypt=true&format=json' | jq

# アラートテンプレートをテスト (通知は送信せず、レンダリングのみ実行)
curl -s -u admin:<pass> -X POST \
  http://localhost:3000/api/alertmanager/grafana/config/api/v1/templates/test \
  -H 'Content-Type: application/json' \
  -d '{"name":"test","template":"{{ define \"test\" }}Alert: {{ .Alerts.Firing | len }} firing{{ end }}","alerts":[{"Status":"firing","Labels":{"alertname":"Test"}}]}'

トラブルシューティング

journalctl -u grafana -f --no-pager

# ダッシュボードにデータが表示されない
# → パネルのデータソースが指す UID が存在するか確認
curl -s -u admin:<pass> http://localhost:3000/api/datasources | jq '.[].uid'
# → データソース自体に到達可能か確認: curl http://localhost:9090/api/v1/query?query=up

# アラートがトリガーされない
# → ルールの datasourceUid が正しいか確認
grep -r datasourceUid /etc/grafana/provisioning/alerting/
# → 評価間隔を確認: /etc/grafana/grafana.ini → [alerting] → evaluation_interval

# Grafana の起動に失敗する
# → 多くの場合、DB の破損または権限の問題: journalctl -u grafana -e
# → /var/lib/grafana/grafana.db が書き込み可能か確認