Alertmanager: 通知テンプレートの展開を確認する #prometheus

はじめに

Alertmanager の通知テンプレートを設定するとき、テンプレートが想定通りに展開されるか手元で確認したいことはないでしょうか。そんなとき、任意のデータを使ってテンプレートを展開できる、amtool の template render サブコマンドが便利です。

amtool のインストール

amtool は、Alertmanager の CLI ツールです。amtool はリリースのバイナリに含まれる他、go get で単体のインストールが可能です。通知テンプレートの展開を行う template render サブコマンドは、v0.23.0 から実装されています。

go get github.com/prometheus/alertmanager/cmd/amtool

テンプレートの展開を確認する

テンプレートの展開には amtool の template render サブコマンドを利用します。

例えば slack.tmpl というテンプレートファイルの slack.text という名前のテンプレートを利用したい場合、以下のように実行します。data.json はテンプレートに渡す JSON 形式のデータ(後述)になります。

amtool template render \
  --template.glob=slack.tmpl \
  --template.text='{{ template "slack.text" . }}' \
  --template.data=data.json

実行後、テンプレートが展開された結果が表示されます。

• *<https://1.example.com/|alert1>*: desc1
• *<https://2.example.com/|alert2>*: desc2

--template.glob は必須の引数になっていますが、/dev/null などダミーを指定することで、 --template-text でテンプレート文字列だけを確認することもできます。

amtool template render \
  --template.glob=/dev/null \
  --template.text='{{- .Status | toUpper }}{{ if eq .Status "firing" }} {{ .Alerts.Firing | len }} ALERTS{{ end }} ({{ .GroupLabels.cluster }})' \
  --template.data=data.json

同様に結果が表示されます。

FIRING 2 ALERTS (cluster-A)

テンプレートデータの準備

テンプレートのデータは --template.data 引数で、JSON 形式のファイルとして指定します。省略時は、デフォルトのダミーデータが使用されます。しかし、ラベルやアノテーションなどのキーや値は環境ごとに違うため、多くの場合は自分でデータを準備する必要があるでしょう。

テンプレートに渡されるデータ形式は NOTIFICATION TEMPLATE REFERENCE に記載されています。例えば前項の確認では、以下のデータを使いました。残念ながら v0.23 時点では YAML 形式には直接対応していませんが、次項で紹介する方法を使って YAML を利用できます。

{
  "Status": "firing",
  "Alerts": [
    {
      "Status": "firing",
      "Labels": {
        "alertname": "alert1"
      },
      "Annotations": {
        "runbook": "https://1.example.com/",
        "description": "desc1"
      }
    },
    {
      "Status": "firing",
      "Labels": {
        "alertname": "alert2"
      },
      "Annotations": {
        "runbook": "https://2.example.com/",
        "description": "desc2"
      }
    }
  ],
  "GroupLabels": {
    "cluster": "cluster-A"
  }
}

YAML 形式でテンプレートデータを利用する

JSON 形式でデータを編集するのが辛い場合、YAML でデータを用意して実行時に JSON に変換するのが便利です。以下の例では bash のプロセス置換(<(command))で yq を使って、data.yaml を JSON に変換しています。

amtool template render \
  --template.glob=/dev/null \
  --template.text='{{- .Status | toUpper }}{{ if eq .Status "firing" }} {{ .Alerts.Firing | len }} ALERTS{{ end }} ({{ .GroupLabels.cluster }})' \
  --template.data=<(yq e -o=json . data.yaml)

おわりに

Alertmanager に限りませんが、テンプレートでは、編集時に余計な空白や改行を付加してしまうようなミスをしがちです。複雑なテンプレートを書いた場合は、ぜひ amtool の template render を活用してみてください。