クリックで作ったダッシュボードは、いつか失うダッシュボードだ
一言でいうと
ダッシュボードの正はファイルにあるべきです。Grafanaのデータベースは、そのファイルを描いて見せている画面にすぎません。
なぜ必要なのか
クリックで作ったダッシュボードが消える経路は、いつも同じです。
- 障害中に急いでパネルをいくつか作ります。役に立ちます。
- 翌週もそのダッシュボードを開きます。チームにリンクを共有します。
- 6か月後に、クラスターを移したりGrafanaを立て直したりします。
- 誰もそのダッシュボードを復元できません。作った人はすでに別のチームです。
ここに、静かな損失がもう1つあります。誰かがしきい線を変えたりパネルを消したりしても、履歴が残りません。「このパネル、もともとなかったっけ?」という質問に答える方法がありません。
どう動くのか
ダッシュボードをファイルとして置くには、2つが必要です。ダッシュボードJSONと、そのディレクトリを見るよう伝えるプロバイダー(provider)ファイルです。この2つを混同することが、最初の関門です。
# provisioning/dashboards/lab.yml — JSON 이 아니라 '어디를 보라' 는 지시다
apiVersion: 1
providers:
- name: lab
type: file
updateIntervalSeconds: 10
allowUiUpdates: false
options:
path: /root/graf/dashboards # ← 여기 있는 *.json 이 대시보드가 된다
こうして提供されたダッシュボードは、APIレスポンスのmeta.provisionedがtrueと出ます。その状態でダッシュボードをAPIで上書きしようとすると、GrafanaがCannot save provisioned dashboardで拒否します。画面とファイルがずれる道を塞いでいるのです。
すでにデータベースに同じuidのダッシュボードがあっても問題ありません。プロビジョニングがそれを引き取ります。クリックで作っておいたダッシュボードをファイルへ移せるのは、そのためです。作るときはUIで楽に作り、終わったらJSONを取り出してファイルに固めればよいのです。
uidはアドレスです
uidを固定することが、この作業の核心です。ダッシュボードのリンクが/d/shop-api/...なので、uidがそのままアドレスであり、アラート・ドキュメント・ブックマーク・ほかのダッシュボードのリンクが、すべてその値を指します。エクスポートしたJSONからuidを消してから入れ直すと、同じダッシュボードが2つになり、リンクは古いほうを指したまま残ります。
よくある勘違い
「exportしたJSONをそのままコミットすれば終わりだ」という考えは不十分です。そのJSONの中には、データソースがuidで埋め込まれています。環境ごとにuidが違うと、ほかの環境では空の画面になります。uidを環境ごとに同じ値で固定するか、データソース自体を変数にしなければなりません。
「idフィールドも一緒にコミットしてよい」という考えは危険です。idは、そのGrafanaの中でだけ意味を持つ通し番号です。移した先で、別のダッシュボードのidとぶつかることがあります。持ち回るJSONでは、uidだけを残してidは消すほうが安全です。
実務で本当に大切なこと
ダッシュボードJSONのdiffは、人が読みにくいものです。座標とフィールドがたくさん動くので、レビューが「LGTM」で流れやすくなります。
そこで、チームで決めておくとよいルールが1つあります。変更されたダッシュボードが答える質問を、PRの説明に1文で書かせることです。その文を書けなければ、その変更はたいていパネルを1つ付け足しただけで、それはこのコースが最初に述べたグラフの壁へ向かう道です。