Grafana 操作手册

Grafana 是数据可视化平台，核心概念: datasource (数据源), dashboard (面板集合), panel (单个图表), alert rule (告警规则), contact point (通知渠道), provisioning (文件驱动的配置管理)。

Provisioning

Grafana 支持通过文件自动创建 dashboard 和 alert rules——不需要手动在 UI 操作。文件修改后 ~10s 自动生效，systemctl reload grafana 强制刷新。

/etc/grafana/provisioning/
├── dashboards/
│   ├── host-provider.yaml              # provider 配置: 哪个文件夹, 从哪读 JSON
│   └── json-all/host/*.json            # dashboard JSON 文件
├── alerting/
│   └── rules.yaml                      # alert rules (含 datasourceUid)
└── datasources/
    └── prometheus.yaml                 # 数据源定义

provider 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 (dashboard JSON 中引用)

Dashboard JSON 调试

# 查看 dashboard 的数据源和 panels
jq '.panels[] | {title, targets: .targets[].expr}' dashboard.json

# 查看模板变量
jq '.templating.list[] | {name, query, current}' dashboard.json

# 批量修改 datasource uid
sed -i 's/"uid": "old-uid"/"uid": "new-uid"/g' dashboard.json

Unified Storage 操作 (Grafana 12+)

Grafana 12 用 SQLite 存储所有对象（unified storage）。UI 建的 dashboard 存在 DB 而非文件中。

systemctl stop grafana
cp /var/lib/grafana/grafana.db grafana.db.bak   # 先备份!

sqlite3 /var/lib/grafana/grafana.db <<SQL
-- 查看 UI 建的 dashboard 和文件夹
SELECT name, kind FROM resource WHERE kind IN ('dashboard', 'folder');

-- 删除 UI 建的 dashboard (provisioned 的由文件管理, 不在这里)
DELETE FROM resource WHERE name = 'old-dashboard' AND kind = 'dashboard';
DELETE FROM resource_history WHERE name = 'old-dashboard';

-- 清理 history 表 (占用可能很大)
SELECT COUNT(*) FROM resource_history;
DELETE FROM resource_history;
SQL

systemctl start grafana

告警

# 列出 contact points
curl -s -u admin:<pass> http://localhost:3000/api/v1/provisioning/contact-points | jq

# 导出含密钥的 contact point
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

# Dashboard 不显示数据
# → 检查 panel datasource 指向的 UID 是否存在
curl -s -u admin:<pass> http://localhost:3000/api/datasources | jq '.[].uid'
# → 检查 datasource 本身是否可达: curl http://localhost:9090/api/v1/query?query=up

# Alert 不触发
# → 检查 rule 的 datasourceUid 是否正确
grep -r datasourceUid /etc/grafana/provisioning/alerting/
# → 检查 evaluation interval: /etc/grafana/grafana.ini → [alerting] → evaluation_interval

# Grafana 启动失败
# → 经常是 DB 损坏或权限问题: journalctl -u grafana -e
# → 检查 /var/lib/grafana/grafana.db 是否可写