使用 Go 的模板语言

本文档主题专为支持 Grafana 9.x 版本的 Grafana 工作空间而设计。

有关支持 Grafana 8.x 版本的 Grafana 工作空间，请参阅。在 Grafana 版本 8 中工作

你可以用 Go 的模板语言（文本 /模板）编写通知模板。

本节概述了 Go 的模板语言和用文本/模板编写模板。

Dot

在文本/模板中，有一个名为 dot 的特殊光标，其写法为。.您可以将此游标视为一个变量，其值会根据其在模板中的使用位置而变化。例如，在通知模板的开头.引用ExtendedData对象，该对象包含多个字段Alerts，包括StatusGroupLabels、CommonLabels、CommonAnnotations和ExternalURL。但是，在列表中使用 dot 时，在列表中使用时，或者在编写要在其他模板中使用的功能模板时with，dot 可能会指其他内容。range你可以在中看到这方面的示例创建通知模板，所有的数据和函数都可以在中看到模板参考。

打开和关闭标签

在文本/模板中，}}无论模板是打印变量还是运行 if 语句等控制结构，模板的开头{{和结尾都是。这与其他模板语言（例如 Jinja）不同，在Jinja中，打印变量使用{{}}和控制结构使用{%和。%}

Print (打印)

要打印某物的值，请使用{{和}}。您可以打印 dot 的值、点的字段、函数的结果和变量的值。例如，要打印 dot 所指的Alerts字段，ExtendedData你可以写下以下内容：

{{ .Alerts }}

迭代警报

要仅打印每个警报的标签，而不是有关警报的所有信息，您可以使用range来迭代警报：ExtendedData

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

范围内的点不再是指ExtendedData，而是指Alert。您可以使用{{ .Labels }}打印每个警报的标签。之所以起作用，是因为{{ range .Alerts }}更改的圆点是指警报列表中的当前警报。范围完成后，点将重置为范围开始之前的值，在本例中为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警报，使点表示警报列表中的当前警报，然后在排序后的标签上使用第二个范围，这样点就会第二次更新以引用当前标签。在第二个范围内.Value，使用.Name和打印每个标签的名称和值：

{{ 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 语句。例如，要在没有警报的情况下进行打印There are no alerts，.Alerts则需要写下以下内容：

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

随着

with 与 if 语句类似，但是与 if 语句不同，它with更新点以引用 with 的值：

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

Variables

文本/模板中的变量必须在模板中创建。例如，要创建一个名为 dot $variable 的变量，其当前值为 dot，你可以写下以下内容：

{{ $variable := . }}

你可以在一个$variable范围内使用 orwith，它将引用定义变量时点的值，而不是 dot 的当前值。

例如，您不能编写{{ .Labels }}在第二个范围内使用的模板，因为这里的点是指当前标签，而不是当前警报：

{{ 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 }}

你可以通过定义一个$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 不会阻止或显示错误消息。

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

嵌入模板

您可以使用在模板中嵌入已定义的模板template，使用双引号中的模板名称以及应传递给模板的光标：

{{ template "print_labels" . }}

将数据传递给模板

模板中的点是指传递给模板的值。

例如，如果向模板传递了触发警报列表，则点表示该触发警报列表：

{{ template "print_alerts" .Alerts }}

如果模板传递了警报的已排序标签，则点表示已排序标签的列表：

{{ 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 }}

但是，模板中的缩进也将出现在文本中。接下来我们将看到如何将其删除。

删除空格和换行符

在文本/模板中，使用{{--}}并删除前导和尾随空格以及换行符。

例如，当使用缩进和换行符使模板更具可读性时：

{{ 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"