本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用消息传递模板
<a name="alert-message-templates"></a>

****  
本文档主题专为支持 **Grafana 8.x 版本**的 Grafana 工作区而设计。  
对于支持 Grafana 10.x 版本的 Grafana 工作区，请参阅[使用 Grafana 版本 10](using-grafana-v10.md)。  
对于支持 Grafana 9.x 版本的 Grafana 工作区，请参阅[使用 Grafana 版本 9](using-grafana-v9.md)。

通过 [使用联系点](alert-contact-points.md) 发送的通知使用*消息传递模板*构建。Grafana 的默认模板基于 [Go 模板系统](https://golang.org/pkg/text/template)，其中一些字段作为文本评估，而另一些字段则作为 HTML 评估（可能会影响转义）。

大部分联系点字段都可以模板化，因此您可以创建可重复使用的自定义模板，并在多个联系点中使用它们。[模板数据](#alert-template-data) 主题列出了可用于创建模板的变量。

**使用模板**

模板用于创建消息。例如，通过 Slack 警报消息，您可以在联系点中设置标题和正文。以下示例展示了如何使用默认模板创建包含警报触发和解决计数的标题，以及列出警报及其状态的正文。
+ **标题**：

  ```
  {{ len .Alerts.Firing }} firing, {{ len .Alerts.Resolved }} resolved
  ```
+ **文本正文**：

  ```
  {{ range .Alerts }}{{ .Status }}: {{ .Labels.alertname }}
  {{end }}
  ```

您可以创建自己的自定义模板，如以下示例所示。
+ **标题**：

  ```
  {{ template "slack.default.title" .}}
  ```
+ **文本正文**：

  ```
  {{ template "mymessage" .}}
  ```

以下是示例模板。

```
{{ define "myalert" }}
  [{{.Status}}] {{ .Labels.alertname }}

  Labels:
  {{ range .Labels.SortedPairs }}
    {{ .Name }}: {{ .Value }}
  {{ end }}

  {{ if gt (len .Annotations) 0 }}
  Annotations:
  {{ range .Annotations.SortedPairs }}
    {{ .Name }}: {{ .Value }}
  {{ end }}
  {{ end }}

  {{ if gt (len .SilenceURL ) 0 }}
    Silence alert: {{ .SilenceURL }}
  {{ end }}
  {{ if gt (len .DashboardURL ) 0 }}
    Go to dashboard: {{ .DashboardURL }}
  {{ end }}
{{ end }}
```

以下过程展示了如何创建、编辑和删除自定义消息模板。

**要创建消息模板**

1. 在 Grafana 控制台的 Grafana 菜单中，选择**警报**（铃铛）图标，打开**警报**页面。

1. 选择**联系点**。

1. 从 **Alertmanager** 下拉列表中，选择要为其创建消息模板的 Alertmanager 实例。默认为 Grafana Alertmanager。

1. 选择**添加模板**。

1. 添加描述性**名称**。

1. 为模板添加**内容**，例如：

   ```
   {{ define "mymessage" }}
     {{ range .Alerts }}
       [{{ .Status }}] {{ range .Labels }} {{ .Name }}={{.Value }}{{end}}
     {{ end }}
   {{ end }}
   ```

   “内容”部分中的 `define` 标签用于指定模板名称。此标签是可选的，如果省略，模板名称将从**名称**字段派生。如果指定了两者，最好的做法是保持一致。

1. 选择**保存模板**。

**注意**  
警报消息模板中的 HTML 将渲染为文本，并转义控制字符。Grafana 不支持在生成的通知中渲染 HTML。

**编辑消息模板**

1. 在**警报**页面，选择**联系点**，以打开联系点列表。

1. 在**模板表**中，找到要编辑的模板，然后选择**编辑**图标（笔）。

1. 进行更改，然后选择**保存模板**。

**删除消息模板**

1. 在**警报**页面，选择**联系点**，以打开联系点列表。

1. 在**模板表**中，找到要移除的模板，然后选择**删除**图标（垃圾桶）。

1. 选择**是，删除**，以删除模板。

**嵌套模板**

您可以将模板嵌入到其他模板中。

例如，你可以使用 `define` 关键字定义一个模板片段：

```
{{ define "mytemplate" }}
  {{ len .Alerts.Firing }} firing. {{ len .Alerts.Resolved }} resolved.
{{ end }}
```

然后，您可以使用 `template` 关键字将自定义模板嵌入到此片段中。例如：

```
Alert summary:
{{ template "mytemplate" . }}
```

您可以使用以下内置模板选项嵌入自定义模板。


| Name | 注意 | 
| --- | --- | 
|  `default.title`  |  显示概览状态信息。  | 
|  `default.message`  |  提供已触发和已解决警报的格式化摘要。  | 

**自定义模板示例**

以下是如何使用自定义模板的示例。

渲染单个警报的模板：

```
{{ define "myalert" }}
  [{{.Status}}] {{ .Labels.alertname }}

  Labels:
  {{ range .Labels.SortedPairs }}
    {{ .Name }}: {{ .Value }}
  {{ end }}

  {{ if gt (len .Annotations) 0 }}
  Annotations:
  {{ range .Annotations.SortedPairs }}
    {{ .Name }}: {{ .Value }}
  {{ end }}
  {{ end }}

  {{ if gt (len .SilenceURL ) 0 }}
    Silence alert: {{ .SilenceURL }}
  {{ end }}
  {{ if gt (len .DashboardURL ) 0 }}
    Go to dashboard: {{ .DashboardURL }}
  {{ end }}
{{ end }}
```

渲染整条通知消息的模板：

```
{{ define "mymessage" }}
  {{ if gt (len .Alerts.Firing) 0 }}
    {{ len .Alerts.Firing }} firing:
    {{ range .Alerts.Firing }} {{ template "myalert" .}} {{ end }}
  {{ end }}
  {{ if gt (len .Alerts.Resolved) 0 }}
    {{ len .Alerts.Resolved }} resolved:
    {{ range .Alerts.Resolved }} {{ template "myalert" .}} {{ end }}
  {{ end }}
{{ end }}
```

## 模板数据
<a name="alert-template-data"></a>

以下数据将传递给消息模板。


| Name | Type | 注意 | 
| --- | --- | --- | 
|  `Receiver`  |  字符串  |  要向其发送通知的联系点的名称。  | 
|  `Status`  |  字符串  |  如果至少有一个警报已触发，则为“触发”，否则为“已解决”。  | 
|  `Alerts`  |  警报  |  此通知中包含的警报对象列表（见下文）。  | 
|  `GroupLabels`  |  KeyValue  |  这些警报的分组标签。  | 
|  `CommonLabels`  |  KeyValue  |  此通知中包含的所有警报的通用标签。  | 
|  `CommonAnnotations`  |  KeyValue  |  此通知中包含的所有警报的通用注释。  | 
|  `ExternalURL`  |  字符串  |  指向发送通知的 Grafana 的返回链接。如果使用外部 Alertmanager，则是指向此 Alertmanager 的返回链接。  | 

`Alerts` 类型公开了两个函数，用于筛选返回的警报。
+ `Alerts.Firing`：返回已触发警报的列表。
+ `Alerts.Resolved`：返回已解决警报的列表。

**警报（类型）**

警报类型包含以下数据。


| Name | Type | 注意 | 
| --- | --- | --- | 
|  Status  |  字符串  |  `firing` 或 `resolved`。  | 
|  标签  |  KeyValue  |  附加到警报的一组标签。  | 
|  Annotations  |  KeyValue  |  附加到警报的一组注释。  | 
|  StartsAt  |  time.Time  |  警报开始触发的时间。  | 
|  EndsAt  |  time.Time  |  仅在知道警报结束时间时设置。否则，设置为从收到最后一次警报的时间起算的可配置的超时周期。  | 
|  GeneratorURL  |  字符串  |  指向 Grafana 或外部 Alertmanager 的返回链接。  | 
|  SilenceURL  |  字符串  |  指向 Grafana 静默的链接，其中预填了此警报的标签。仅适用于 Grafana 管理的警报。  | 
|  DashboardURL  |  字符串  |  指向 Grafana 控制面板的链接（适用于警报规则属于 Grafana 控制面板的情况）。仅适用于 Grafana 管理的警报。  | 
|  PanelURL  |  字符串  |  指向 Grafana 控制面板中面板的链接（适用于警报规则属于 Grafana 控制面板中面板的情况）。仅适用于 Grafana 管理的警报。  | 
|  指纹  |  字符串  |  可用于识别警报的指纹。  | 
|  ValueString  |  字符串  |  该字符串包含警报中每个简化表达式的标签和值。  | 

**KeyValue type**

`KeyValue`类型是一组表示标签和注释的 key/value 字符串对。

除了直接访问存储为 `KeyValue` 的数据外，还有方法可以对这些数据进行排序、删除和转换。


| Name | 参数 | 返回值 | 注意 | 
| --- | --- | --- | --- | 
|  SortedPairs  |    |  键值字符串对的排序列表  |    | 
|  删除  |  []string  |  KeyValue  |  返回没有给定键 Key/Value 的地图副本。  | 
|  名称  |    |  []string  |  标签名称列表  | 
|  值  |    |  []string  |  标签值列表  | 



## 模板函数
<a name="alert-template-functions"></a>

使用模板函数，您可以处理标签和注释，以生成动态通知。可使用以下函数。


| Name | 参数类型 | 返回类型 | 说明 | 
| --- | --- | --- | --- | 
|  `humanize`  |  数字或字符串  |  字符串  |  使用公制前缀将数字转换为更易读的格式。  | 
|  `humanize1024`  |  数字或字符串  |  字符串  |  与 humanize 类似，但使用 1024 作为基数，而不是 1000。  | 
|  `humanizeDuration`  |  数字或字符串  |  字符串  |  将以秒为单位的持续时间转换为更易读的格式。  | 
|  `humanizePercentage`  |  数字或字符串  |  字符串  |  将比率值转换为百分比。  | 
|  `humanizeTimestamp`  |  数字或字符串  |  字符串  |  将以秒为单位的 Unix 时间戳转换为更易读的格式。  | 
|  `title`  |  字符串  |  字符串  |  strings.Title，将每个单词的第一个字符大写。  | 
|  `toUpper`  |  字符串  |  字符串  |  字符串。 ToUpper，将所有字符转换为大写。  | 
|  `toLower`  |  字符串  |  字符串  |  字符串。 ToLower，将所有字符转换为小写。  | 
|  `match`  |  模式、文本  |  布尔值  |  regexp。 MatchString 测试未锚定的正则表达式匹配。  | 
|  `reReplaceAll`  |  模式、置换、文本  |  字符串  |  Regexp。 ReplaceAllString 正则表达式替换，未锚定。  | 
|  `graphLink`  |  字符串：包含 `expr` 和 `datasource` 字段的 JSON 对象  |  字符串  |  返回给定表达式和数据来源在 Explore 中图形视图的路径。  | 
|  `tableLink`  |  字符串：包含 `expr` 和 `datasource` 字段的 JSON 对象  |  字符串  |  返回给定表达式和数据来源在 Explore 中表格视图的路径。  | 
|  `args`  |  []interface\$1\$1  |  map[string]interface\$1\$1  |  将对象列表转换为带键的映射，例如 arg0、arg1。使用此函数可将多个参数传递给模板。  | 
|  `externalURL`  |  nothing  |  字符串  |  返回代表外部 URL 的字符串。  | 
|  `pathPrefix`  |  nothing  |  字符串  |  返回外部 URL 的路径。  | 

下表列出了每个函数的使用示例。


| 函数 | TemplateString | Input | 预期 | 
| --- | --- | --- | --- | 
|  humanize  |  \$1 humanize \$1value \$1  |  1234567.0  |  1.235M  | 
|  humanize1024  |  \$1 humanize1024 \$1value \$1  |  1048576.0  |  1Mi  | 
|  humanizeDuration  |  \$1 humanizeDuration \$1value \$1  |  899.99  |  14m 59s  | 
|  humanizePercentage  |  \$1 humanizePercentage \$1value \$1  |  0.1234567  |  12.35%  | 
|  humanizeTimestamp  |  \$1 humanizeTimestamp \$1value \$1  |  1435065584.128  |  2015-06-23 13:19:44.128 \$10000 UTC  | 
|  删除实例快照  |  \$1 \$1value \$1 title \$1  |  aa bB CC  |  Aa Bb Cc  | 
|  toUpper  |  \$1 \$1value \$1 toUpper \$1  |  aa bB CC  |  AA BB CC  | 
|  toLower  |  \$1 \$1value \$1 toLower \$1  |  aa bB CC  |  aa bb cc  | 
|  match  |  \$1 match "a\$1" \$1labels.instance \$1  |  aa  |  true  | 
|  reReplaceAll  |  \$1\$1 reReplaceAll “localhost :( .\$1)” “我的.domain：\$11" \$1labels.instance\$1\$1  |  localhost:3000  |  my.domain:3000  | 
|  graphLink  |  \$1\$1 graphLink "\$1\$1"expr\$1": \$1"up\$1", \$1"datasource\$1": \$1"gdev-prometheus\$1"\$1" \$1\$1  |    |  /explore?left=["now-1h","now","gdev-prometheus",\$1"datasource":"gdev-prometheus","expr":"up","instant":false,"range":true\$1]  | 
|  tableLink  |  \$1\$1 tableLink "\$1\$1"expr\$1":\$1"up\$1", \$1"datasource\$1":\$1"gdev-prometheus\$1"\$1" \$1\$1  |    |  /explore?left=["now-1h","now","gdev-prometheus",\$1"datasource":"gdev-prometheus","expr":"up","instant":true,"range":false\$1]  | 
|  args  |  \$1\$1define "x"\$1\$1\$1\$1.arg0\$1\$1 \$1\$1.arg1\$1\$1\$1\$1end\$1\$1\$1\$1template "x" (args 1 "2")\$1\$1  |    |  1 2  | 
|  externalURL  |  \$1 externalURL \$1  |    |  http://localhost/path/prefix  | 
|  pathPrefix  |  \$1 pathPrefix \$1  |    |  /path/prefix  |