Go のテンプレート言語の使用

このドキュメントのトピックは、Grafana バージョン 9.x をサポートする Grafana ワークスペース向けです。

Grafana バージョン 10.x をサポートする Grafana ワークスペースについては、「Grafana バージョン 10 での作業」を参照してください。

Grafana バージョン 8.x をサポートする Grafana ワークスペースについては、「Grafana バージョン 8 での作業」を参照してください。

Go のテンプレート言語である text/template で通知テンプレートを書き込みます。

このセクションでは、Go のテンプレート言語の概要と、text/template でのテンプレートの作成について説明します。

dot

text/template には dot と呼ばれる特別なカーソルがあり、. として記述されます。このカーソルは、テンプレート内の使用場所に応じて値が変化する変数と考えることができます。例えば、通知テンプレートの開始時に . は、Alerts、Status、GroupLabels、CommonLabels、CommonAnnotations および ExternalURL を含む多数のフィールドを含む ExtendedData オブジェクトを参照します。ただし、dot は、リスト上の range で使用される場合、with 内で使用される場合、または他のテンプレートで使用する機能テンプレートを記述する場合、他の何かを参照する場合があります。これの例は 通知テンプレートの作成 で、すべてのデータと関数は テンプレートリファレンス で確認できます。

開始と終了のタグ

テキスト/テンプレートでは、テンプレートが変数を印刷するか、if ステートメントなどのコントロール構造を実行するかに関係なく、テンプレートは {{で始まり、}} で終わります。これは、変数の出力に {{ と }} を使用し、制御構造に {% と %} を使用する Jinja などの他のテンプレート言語とは異なります。

印刷

何かの値を印刷するには、{{ と }} を使用します。dot の値、dot のフィールド、関数の結果、[変数]の値を印刷できます。例えば、dot が ExtendedData を参照する Alerts フィールドを印刷するには、次のように記述します。

{{ .Alerts }}

アラートを反復処理する

アラートに関するすべての情報ではなく、各アラートのラベルのみを印刷するには、range を使用して ExtendedData でアラートを反復処理できます。

{{ range .Alerts }}
{{ .Labels }}
{{ end }}

範囲内の dot は、ExtendedData ではなく Alert を参照します。{{ .Labels }} を使用して、各アラートのラベルを印刷できます。これは、アラートのリスト内の現在のアラートを参照するように {{ range .Alerts }} が dot を変えるために機能します。範囲が終了すると、dot は範囲の開始前に存在していた値にリセットされます。この例では ExtendedData です。

{{ range .Alerts }}
{{ .Labels }}
{{ end }}
{{/* does not work, .Labels does not exist here */}}
{{ .Labels }}
{{/* works, cursor was reset */}}
{{ .Status }}

注釈とラベルを反復処理する

各アラートのラベルを The name of the label is $name, and the value is $value の形式で印刷するテンプレートを書きましょう。ここで、$name と $value には各ラベルの名前と値が含まれます。

前の例と同様に、.Alerts の範囲を使用して のアラートを繰り返し、dot がアラートのリスト内の現在のアラートを参照するようにし、ソートされたラベルで 2 番目の範囲を使用して、dot が現在のラベルを参照するように 2 回目に更新されます。2 番目の範囲内では、 .Name と .Value を使用して各ラベルの名前と値を出力します。

{{ range .Alerts }}
{{ range .Labels.SortedPairs }}
The name of the label is {{ .Name }}, and the value is {{ .Value }}
{{ end }}
{{ range .Annotations.SortedPairs }}
The name of the annotation is {{ .Name }}, and the value is {{ .Value }}
{{ end }}
{{ end }}

If ステートメント

テンプレートでは if ステートメントを使用できます。例えば、.Alerts にアラートがない場合に There are no alerts を出力するには、次のように記述します。

{{ if .Alerts }}
There are alerts
{{ else }}
There are no alerts
{{ end }}

With

With は if ステートメントと似ていますが、if ステートメントとは異なり、with は dot を更新して with の値を参照します。

{{ with .Alerts }}
There are {{ len . }} alert(s)
{{ else }}
There are no alerts
{{ end }}

変数

text/template の変数は、テンプレート内に作成する必要があります。例えば、$variable という変数を現在の dot の値で作成するには、次のように記述します。

{{ $variable := . }}

範囲内の $variable または with を使用でき、これらは変数が定義された時点の dot の値を参照します。dot の現在の値は参照されません。

例えば、2 番目の範囲で {{ .Labels }} を使用するテンプレートを記述することはできません。ここでは、現在のアラートではなく、現在のラベルが dot で参照されるためです。

{{ range .Alerts }}
{{ range .Labels.SortedPairs }}
{{ .Name }} = {{ .Value }}
{{/* does not work because in the second range . is a label not an alert */}}
There are {{ len .Labels }}
{{ end }}
{{ end }}

これを修正するには、最初の範囲と 2 番目の範囲の前に $alert という変数を定義します。

{{ range .Alerts }}
{{ $alert := . }}
{{ range .Labels.SortedPairs }}
{{ .Name }} = {{ .Value }}
{{/* works because $alert refers to the value of dot inside the first range */}}
There are {{ len $alert.Labels }}
{{ end }}
{{ end }}

インデックスを含む範囲

範囲の開始時にインデックス変数と値変数を定義することで、範囲内の各アラートのインデックスを取得できます。

{{ $num_alerts := len .Alerts }}
{{ range $index, $alert := .Alerts }}
This is alert {{ $index }} out of {{ $num_alerts }}
{{ end }}

テンプレートの定義

define とテンプレートの名前を二重引用符で囲むことで、他のテンプレート内で使用できるテンプレートを定義できます。__subject、__text_values_list、__text_alert_list、default.title、default.message などのデフォルトテンプレートを含め、他のテンプレートと同じ名前のテンプレートを設定しないでください。デフォルトテンプレートと同じ名前のテンプレート、または別の通知テンプレート内のテンプレートと同じ名前で作成されている場合、Grafana はいずれかのテンプレートを使用することになり、混乱が生じます。Grafana は、同じ名前のテンプレートが 2 つ以上ある場合、エラーメッセージを返しません。

{{ define "print_labels" }}
{{ end }}

テンプレートを埋め込む

template、二重引用符で囲まれたテンプレートの名前、およびテンプレートに渡されるカーソルを使用して、テンプレート内で定義されたテンプレートを埋め込むことができます。

{{ template "print_labels" . }}

テンプレートにデータを渡す

テンプレート内では、dot はテンプレートに渡される値を参照します。

例えば、テンプレートに発射アラートのリストが渡された場合、dot は発射アラートのリストを参照します。

{{ template "print_alerts" .Alerts }}

テンプレートにアラートのソート済みラベルが渡された場合、dot はソート済みラベルのリストを参照します。

{{ template "print_labels" .SortedLabels }}

これは、再利用可能なテンプレートを記述する場合に役立ちます。例えば、すべてのアラートを出力するには、次のように記述します。

{{ template "print_alerts" .Alerts }}

次に、発射アラートのみを出力するには、次のように記述します。

{{ template "print_alerts" .Alerts.Firing }}

これは、.Alerts と .Alerts.Firing の両方がアラートのリストであるために機能します。

{{ define "print_alerts" }}
{{ range . }}
{{ template "print_labels" .SortedLabels }}
{{ end }}
{{ end }}

コメント

{{/* および */}} を使用してコメントを追加できます。

{{/* This is a comment */}}

コメントが改行を追加しないようにするには、以下を使用します。

{{- /* This is a comment with no leading or trailing line breaks */ -}}

インデント

タブとスペースの両方のインデントと改行を使用して、テンプレートをより読みやすくすることができます。

{{ range .Alerts }}
  {{ range .Labels.SortedPairs }}
    {{ .Name }} = {{ .Value }}
  {{ end }}
{{ end }}

ただし、テンプレートのインデントはテキストにも適用されます。次に、削除する方法を説明します。

スペースと改行を削除する

text/template では、 {{- と -}} を使用して、先頭と末尾のスペースと改行を削除します。

例えば、インデントと改行を使用してテンプレートをより読みやすくする場合です。

{{ range .Alerts }}
  {{ range .Labels.SortedPairs }}
    {{ .Name }} = {{ .Value }}
  {{ end }}
{{ end }}

インデントと改行はテキストにも表示されます。

    alertname = "Test"

    grafana_folder = "Test alerts"

各範囲の先頭の }} を -}} に変更することで、テキストからインデントと改行を削除できます。

{{ range .Alerts -}}
  {{ range .Labels.SortedPairs -}}
    {{ .Name }} = {{ .Value }}
  {{ end }}
{{ end }}

これにより、テンプレートのインデントと改行がテキストから取り除かれます。

alertname = "Test"
grafana_folder = "Test alerts"