菜单

模板参考

Grafana Cloud Enterprise 开源

通知模板参考

默认情况下，Grafana 提供预定义模板来格式化通知消息。

您还可以使用自定义模板自定义通知，这些模板基于 Go 模板语言。

本文档列出了通知模板中可用的数据。

通知数据

在通知模板中，点号（.）使用以下数据进行初始化

名称	类型	描述
`接收者`	字符串	发送通知的联系点名称
`状态`	字符串	如果至少有一个告警正在触发，则状态为 `firing`，否则为 `resolved`。
`告警列表`	[] Alert	此通知中所有触发和已解决的告警列表。
`Alerts.Firing`	[] Alert	此通知中所有触发告警的列表。
`Alerts.Resolved`	[] Alert	此通知中所有已解决告警的列表。
`分组标签`	KV	根据 `Group by` 选项将这些告警在此通知中分组的标签。
`公共标签`	KV	此通知中所有告警共有的标签。
`公共注解`	KV	此通知中所有告警共有的注解。
`外部 URL`	字符串	Grafana 的链接，或者如果使用外部 Alertmanager 则为发送此通知的 Alertmanager 的链接。
`分组键`	字符串	用于标识此告警组的键。
`截断的告警数量`	整数	通知中截断的告警数量（如果有）。由 Webhook 和 OnCall 支持。

请务必记住，单个通知可以将多个告警分组以减少您收到的告警数量。Alerts 是一个数组，包含通知中的所有告警。

这里有一个示例，打印点号（.）中所有可用的通知数据。

{{ define "custom_template" }}
  {{ .Receiver }}
  {{ .Status }}
  There are {{ len .Alerts }} alerts
  There are {{ len .Alerts.Firing }} firing alerts
  There are {{ len .Alerts.Resolved }} resolved alerts
  {{ .GroupLabels }}
  {{ .CommonLabels }}
  {{ .CommonAnnotations }}
  {{ .ExternalURL }}
{{ end }}

您可以通过传递点号（.）来执行此模板。

{{ template "custom_template" . }}

告警

Alert 包含单个告警的数据

名称	类型	描述
`状态`	字符串	触发中或已解决。
`标签`	KV	与此告警关联的标签。它包含所有类型的标签，但仅包含告警条件中使用的查询标签。
`注解`	KV	此告警的注解。
`开始时间`	时间	告警触发的时间
`结束时间`	时间	仅当告警的结束时间已知时设置。否则设置为自收到最后一个告警以来的可配置超时时段。
`生成器 URL`	字符串	Grafana 的链接，或者如果使用外部告警生成器则为告警源的链接。
`指纹`	字符串	标识告警的唯一字符串。

Grafana 管理的告警包含以下附加属性

名称	类型	描述
`仪表盘 URL`	字符串	如果告警具有仪表盘 UID 注解，则为 Grafana 仪表盘的链接。
`面板 URL`	字符串	如果告警具有面板 ID 注解，则为面板的链接。
`静默 URL`	字符串	静默告警的链接。
`值`	KV	用于评估告警条件的表达式的值。仅包含相关值。
`值字符串`	字符串	一个字符串，包含告警中每个简化表达式的标签和值。
`组织 ID`	整数	拥有此告警的组织 ID。

此示例迭代通知中的触发和已解决告警列表（.Alerts），并打印每个告警的数据

{{ define "custom_template" }}
{{ range .Alerts }}
  {{ .Status }}
  {{ .Labels }}
  {{ .Annotations }}
  {{ .StartsAt }}
  {{ .EndsAt }}
  {{ .GeneratorURL }}
  {{ .Fingerprint }}

  {{/* Only available for Grafana-managed alerts */}}
  {{ .DashboardURL }}
  {{ .PanelURL }}
  {{ .SilenceURL }}
  {{ .Values }}
  {{ .ValueString }}
{{ end }}
{{ end }}

您可以通过传递点号（.）来运行此模板。

{{ template "custom_template" . }}

KV

KV 是一组键值对，其中每个键和值都是字符串。

类似于访问变量属性，您可以使用 . 来检索值的value。例如

{{ define "custom_template" }}
  {{ .CommonLabels.grafana_folder }}
{{ end }}

如果 KV 恰好包含数字或布尔值，则它们是数字或布尔值的字符串表示。

此外，KV 提供方法来对键值对进行排序、移除键以及仅迭代键或值

方法名称	描述	参数	返回值
SortedPairs	返回排序后的键/值对列表。		Pairs
Remove	返回移除指定键后的 KV 副本	[]string	KV
Names	返回标签名称的列表		[]string
值	返回值的列表		[]string

这里是使用这些方法的示例

{{ define "custom_template" }}
  {{ .CommonLabels.SortedPairs }}
  {{ .CommonLabels.Names }}
  {{ .CommonLabels.Values }}
  {{ .CommonLabels.Remove (stringSlice "grafana_folder") }}
{{ end }}

时间

一些模板函数和属性返回一个 Time 对象，它引用 Go 的 time 包中的 Time 类型。

访问 Time 对象时，您可以在模板中使用各种 Time 函数，如下所示。

{{ define "custom_template" }}
  {{ range .Alerts }}
    {{ .StartsAt  }}
    {{ .StartsAt.Add 6000000000000  }}
    {{ .StartsAt.Add -6000000000000  }}
    {{ .StartsAt.AddDate 1 0 0  }}
    {{ .StartsAt.Year   }}/{{ .StartsAt.Month   }}/{{ .StartsAt.Day   }}
    {{ .StartsAt.Hour   }}:{{ .StartsAt.Minute   }}:{{ .StartsAt.Second   }}
    {{ .StartsAt.YearDay   }}-{{ .StartsAt.Weekday   }}
    {{ .StartsAt.Unix }} {{ .StartsAt.UnixMilli }}
  {{ end}}
{{ end }}

函数

函数可以在模板中执行操作，例如转换或格式化数据。

请注意，Go 模板语言提供的函数（例如 index、and、printf 和 len）以及许多其他函数都是可用的。

此外，以下函数也可用于模板化通知

名称	参数	返回值	描述
`title`	字符串	字符串	将每个单词的首字母大写。
`toUpper`	字符串	字符串	将所有文本转换为大写。
`toLower`	字符串	字符串	将所有文本转换为小写。
`trimSpace`	字符串	字符串	移除开头和结尾的空白字符。
`match`	pattern, text	布尔值	根据正则表达式模式匹配文本。
`reReplaceAll`	pattern, replacement, text	字符串	替换匹配正则表达式的文本。
`join`	sep string, s []string	字符串	将 s 的元素连接起来创建一个字符串。分隔符 sep 放置在结果字符串的元素之间。
`safeHtml`	字符串	字符串	将字符串标记为 HTML，无需自动转义。
`stringSlice`	…string	字符串	将传入的字符串作为字符串切片返回。
`date`	string, Time	字符串	以指定格式格式化时间。有关格式选项，请参阅 Go 的 time format 文档。
`tz`	string, Time	时间	以指定时区（例如 `Europe/Paris`）返回时间。有关可用时区选项，请参阅 tz 数据库时区列表。

这里有一个使用一些函数格式化文本的示例

{{ define "custom_template" }}
  {{ title "hello, world!" }}
  {{ toUpper "Hello, world!" }}
  {{ toLower "Hello, world!" }}
  {{ trimSpace "Hello, world!" }}
  {{ match "a.*" "abc" }}
  {{ reReplaceAll "localhost:(.*)" "example.com:$1" "localhost:8080" }}
  {{ join "-" (stringSlice "a" "b" "c") }}
  {{ safeHtml "<b>Text</b>"}}
  {{ stringSlice "a" "b" "c" }}
{{ end }}

date 和 tz 可以格式化时间。例如，要以 15:04:05 MST 格式打印告警触发的时间

{{ define "custom_template" }}
  {{ range .Alerts }}
    {{ .StartsAt | date "15:04:05 MST" }}
  {{ end}}
{{ end }}

然后，您可以使用 tz 将时区从 UTC 更改为本地时间，例如 Europe/Paris。

{{ define "custom_template" }}
  {{ range .Alerts }}
    {{ .StartsAt | tz "Europe/Paris" }}
    {{ .StartsAt | tz "Europe/Paris" | date "15:04:05 MST" }}
  {{ end}}
{{ end }}

2024-10-30 21:01:45.227 +0100 CET
21:01:45 CET

命名空间函数

除了顶级函数外，还提供以下命名空间函数

集合函数

名称	参数	返回值	描述
`coll.Dict`	key string, value any, …	map	从键/值对创建带有字符串键的 map。所有键都转换为字符串。如果提供的参数数量为奇数，则最后一个键的值将为空字符串。
`coll.Slice`	…any	[]any	从提供的参数创建 slice (数组/列表)。对于创建可使用 `range` 迭代的列表很有用。
`coll.Append`	value any, list []any	[]any	通过将一个值附加到现有列表的末尾来创建一个新列表。不修改原始列表。

使用集合函数的示例

{{ define "collection.example" }}
{{- /* Create a dictionary of alert metadata */ -}}
{{- $metadata := coll.Dict
    "severity" "critical"
    "team" "infrastructure"
    "environment" "production"
-}}

{{- /* Create a slice of affected services */ -}}
{{- $services := coll.Slice "database" "cache" "api" -}}

{{- /* Append a new service to the list */ -}}
{{- $services = coll.Append "web" $services -}}

{{- /* Use the collections in a template */ -}}
Affected Services: {{ range $services }}{{ . }},{{ end }}

Alert Metadata:
{{- range $k, $v := $metadata }}
  {{ $k }}: {{ $v }}
{{- end }}
{{ end }}

输出

Affected Services: database,cache,api,web,

Alert Metadata:
  environment: production
  severity: critical
  team: infrastructure

数据函数

名称	参数	返回值	描述
`data.JSON`	jsonString string	any	将 JSON 字符串解析为可在模板中操作的对象。适用于 JSON 对象和数组。
`data.ToJSON`	obj any	字符串	将任何对象（map、数组等）序列化为 JSON 字符串。对于创建 webhook Payload 很有用。
`data.ToJSONPretty`	indent string, obj any	字符串	创建对象的缩进 JSON 字符串表示形式。第一个参数指定缩进字符串（例如空格）。

使用数据函数的示例

{{ define "data.example" }}
{{- /* First, let's create some alert data as a JSON string */ -}}
{{ $jsonString := `{
  "service": {
    "name": "payment-api",
    "environment": "production",
    "thresholds": {
      "error_rate": 5,
      "latency_ms": 100
    }
  }
}` }}

{{- /* Parse the JSON string into an object we can work with */ -}}
{{ $config := $jsonString | data.JSON }}

{{- /* Create a new alert payload */ -}}
{{ $payload := coll.Dict
    "service" $config.service.name
    "environment" $config.service.environment
    "status" .Status
    "errorThreshold" $config.service.thresholds.error_rate
}}

{{- /* Output the payload in different JSON formats */ -}}
Compact JSON: {{ $payload | data.ToJSON }}

Pretty JSON with 2-space indent:
{{ $payload | data.ToJSONPretty "  " }}
{{ end }}

输出

Compact JSON: {"environment":"production","errorThreshold":5,"service":"payment-api","status":"resolved"}

Pretty JSON with 2-space indent:
{
  "environment": "production",
  "errorThreshold": 5,
  "service": "payment-api",
  "status": "resolved"
}

模板函数

名称	参数	返回值	描述
`tmpl.Exec`	name string, [context any]	字符串	执行具名模板并将结果作为字符串返回。类似于 `template` 操作，但允许对结果进行后处理。
`tmpl.Inline`	template string, context any	字符串	将字符串渲染为模板。

{{ define "template.example" -}}
{{ coll.Dict
    "info" (tmpl.Exec `info` . | data.JSON)
    "severity" (tmpl.Inline `{{ print "critical" | toUpper }}` . )
    | data.ToJSONPretty " "}}
{{- end }}

{{- /* Define a sub-template */ -}}
{{ define "info" -}}
{{coll.Dict
    "team" "infrastructure"
    "environment" "production" | data.ToJSON }}
{{- end }}

输出

{
  "info": {
    "environment": "production",
    "team": "infrastructure"
  },
  "severity": "CRITICAL"
}

时间函数

名称	参数	返回值	描述
`time.Now`		时间	将当前本地时间作为 time.Time 对象返回。可以使用 Go 的 time 格式化函数进行格式化。

使用时间函数的示例

{{ define "time.example" }}
{{- /* Get current time in different formats */ -}}
Current Time (UTC): {{ (time.Now).UTC.Format "2006-01-02 15:04:05 MST" }}
Current Time (Local): {{ (time.Now).Format "Monday, January 2, 2006 at 15:04:05" }}

{{- /* Compare alert time with current time */ -}}
{{ $timeAgo := (time.Now).Sub .StartsAt }}
Alert fired: {{ $timeAgo }} ago
{{ end }}

输出

Current Time (UTC): 2025-03-08 18:14:27 UTC
Current Time (Local): Saturday, March 8, 2025 at 14:14:27
Alert fired: 25h49m32.78574723s ago

与注解和标签模板的区别

在告警规则中，您还可以模板化注解和标签以包含附加信息。例如，您可以添加一个 summary 注解，显示触发告警的查询值。

注解和标签模板为单个告警实例添加相关信息，而通知模板则提供关于一组告警实例的信息。

由于这两种类型的模板在不同的上下文（context）中运行，因此注解和标签模板中可用的函数和变量与通知模板中使用的不同。

此页面是否有帮助？

在 GitHub 中提出编辑建议

创建 GitHub Issue

发送邮件至 docs@grafana.com

帮助与支持

社区