grafana

GrafanaのDashboard等をファイルで管理する

Grafanaのdatasourceとdashboardは従来REST APIか、GUIを通じてしかexport/importできなくて、Git等で管理するのに少し工夫が必要だったのだけど、v5.0からファイルでの管理に対応した。それについてドキュメント読んでメモしただけの記事。

Provisioning | Grafana Documentation

ファイルで管理できると、AnsibleやDockerとの相性も良くなってとても楽。

Datasources

/etc/grafana/provisioning/datasources/hoge.yml に設定を以下のように書く。datasourceが複数ある場合、ファイルは分割しても良いし、 datasources にmapで複数指定してもよい。

apiVersion: 1

datasources:
- name: timeseriesData
  type: influxdb
  access: proxy
  orgId: 1
  url: http://192.0.1.1:8086
  user: user
  password: password
  database: timeseries
  isDefault: true
  editable: false
  version: 1

設定を更新したときに version をincrementしておけば、古いversionで新しいversionは上書きできなくなっているので安心、みたいなこともドキュメントには書かれているのだが、どうも上手く動かなくて使い方がわからない。

editable がデフォルトで false になっており、yamlでprovisioningした設定は、GUIからは書き換えできなくなっている。これはyamlからその設定を削除した後も有効。yamlで追加したdatasourceを消すには、 editable: true にしてGUIから消すか、 delete_datasources に設定するかの2択。

一意性

name で判断されている。既存のdatasourceと同じ name を持つ設定をyamlで準備した場合、yamlの値が優先されて、上書きされてしまうため注意が必要。

Dashboards

こちらは2箇所に設定が必要。まず /etc/grafana/provisioning/dashboards/hoge.yml を置く。

apiVersion: 1

providers:
- name: 'hoge'
  orgId: 1
  folder: ''
  type: file
  disableDeletion: true
  editable: true
  options:
    path: /var/lib/grafana/dashboards

ここで書いた name はGUIだと特にどこでも使われていないと思うので、なんでもいい。これは単に、実際のdashboardのjsonを providers[0].options.path に置きますよという宣言をしているだけ。あとは diableDeletioneditable はお好みに応じて。ドキュメントに各設定値の詳細が書かれていないので、今のところ挙動がわかりにくいが、disableDeletion: true にしておくと、jsonを削除してもdashboardは削除されなくなる。

実際のjsonは、この場合では /var/lib/grafana/dashboards に1つずつ配置する。このjsonは、従前のバージョンからGUIで出力できていた、あの書式で良い。あまりGrafana dashboardをjsonでイチから書く人もいないと思うので、一旦GUIで作ってからexportすればOK。但し、exportした際には付与される id という値が、ファイルでのprovisioningの場合は不要となっているので、削っておく必要がある。

一意性

uid で管理される。uidはGUIから作成したdashboardだとランダムに採番されていて、yamlから作成するときはjsonの中で好きに採番できる(採番しなくてもOKで、その場合はやはりランダムになる)。すでに存在するuidと同じuidでjson設定を書いた場合、そのuidのdashboardが強制的に更新される。uidはdashboardのURLに含まれるため、複数のGrafanaを立てて、同じグラフを双方で表示するとき、一意なURL採番をするのに役立つ。

ただし、注意するべきは title も一意である必要があるということ。例えば1つのGrafanaサーバーに、 title が同一で、 uid は異なるdashboard設定を複数用意しても、後発の設定は反映されない。GUIですでに存在するdashboardの設定をjsonファイルで配置し、別uidを振ったとしても、既存の方のdashboardを一度削除しないことには、jsonの方は反映されない。