本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 模板化标签和注释
****
本文档主题专为支持 **Grafana 9.x 版本**的 Grafana 工作区而设计。
对于支持 Grafana 10.x 版本的 Grafana 工作区，请参阅[使用 Grafana 版本 10](using-grafana-v10.md)。
对于支持 Grafana 8.x 版本的 Grafana 工作区，请参阅[使用 Grafana 版本 8](using-grafana-v8.md)。
在 Grafana 中，您可以像在 Prometheus 中一样对标签和注释进行模板化。如果您之前使用过 Prometheus，那么应该熟悉 `$labels` 和 `$value` 变量，包括警报的标签和值。即使警报不使用 Prometheus 数据来源，您也可以在 Grafana 中使用相同的变量。如果您以前没有使用过 Prometheus，请不要担心，因为本页的其余部分将介绍这些变量以及如何对其模板化。
## Go 的模板语言
标签和注释的模板是用 Go 的模板语言 [text/template](https://pkg.go.dev/text/template) 编写的。
**开始和结束标签**
在 text/template 中，模板以 `{{` 开头，以 `}}` 结尾，无论模板是打印变量还是运行 if 语句等控制结构。这与 Jinja 等其他模板语言不同，在 Jinja 中，打印变量使用 `{{` 和 `}}`，控制结构使用 `{%` 和 `%}`。
**Print (打印)**
要打印某项的值，请使用 `{{` 和 `}}`。您可以打印函数的结果或变量的值。例如，要打印 `$labels` 变量，您可以编写以下内容：
```
{{ $labels }}
```
**遍历标签**
要遍历 `$labels` 中的每个标签，可以使用 `range`。这里 `$k` 是指名称，`$v` 是指当前标签的值。例如，如果您的查询返回一个标签 `instance=test`，那么 `$k` 将是 `instance`，`$v` 将是 `test`。
```
{{ range $k, $v := $labels }}
{{ $k }}={{ $v }}
{{ end }}
```
## 标签、值和值变量
**标签变量**
`$labels` 变量包含查询中的标签。例如，检查实例是否关闭的查询可能会返回带有关闭实例名称的实例标签。例如，假设有一个警报规则，当其中一个实例关闭超过 5 分钟时，该规则会触发。您希望向警报添加摘要，告诉您哪个实例已关闭。使用 `$labels` 变量，您可以创建摘要，在摘要中打印实例标签：
```
Instance {{ $labels.instance }} has been down for more than 5 minutes
```
**带点的标签**
如果您要打印的标签名称中包含点（句号或句点），则在模板中使用相同的点将不起作用：
```
Instance {{ $labels.instance.name }} has been down for more than 5 minutes
```
这是因为模板尝试使用 `$labels.instance` 中不存在的字段（名为 `name`）。您应该改用 `index` 函数，该函数会在 `$labels` 变量中打印标签 `instance.name`：
```
Instance {{ index $labels "instance.name" }} has been down for more than 5 minutes
```
**值变量**
`$value` 变量的工作原理与 Prometheus 不同。在 Prometheus 中，`$value` 是一个包含表达式值的浮点数，但在 Grafana 中，却是一个字符串，包含该警报规则的所有阈值、Reduce 和 Math 表达式以及经典条件的标签和值。但不包含查询的结果，因为这些查询可以返回 10 到 10000 行或指标。
如果您要在警报摘要中使用 `$value` 变量：
```
{{ $labels.service }} has over 5% of responses with 5xx errors: {{ $value }})
```
摘要看起来如下所示：
```
api has an over 5% of responses with 5xx errors: [ var='B' labels={service=api} value=6.789 ]
```
这里 `var='B'` 指的是带有 RefID B 的表达式。在 Grafana 中，所有查询和表达式都由 RefID 标识，该 ReFID 标识警报规则中的每个查询和表达式。同样，`labels={service=api}` 是指标签，`value=6.789` 是指值。
您可能已经注意到没有 RefID A。这是因为在大多数警报规则中，RefID A 指的是查询，而由于查询可以返回许多行或时间序列，因此并不包含在 `$value` 规则中。
**值变量**
如果 `$value` 变量包含的信息超出了您的需求，则可以使用 `$values` 打印单个表达式的标签和值。不同于 `$value`，`$values` 变量是一个对象表，包含每个表达式的标签和浮点值，按其 RefID 索引。
如果要在警报摘要中打印带有 RefID `B` 的表达式值：
```
{{ $labels.service }} has over 5% of responses with 5xx errors: {{ $values.B }}%
```
摘要将仅包含以下值：
```
api has an over 5% of responses with 5xx errors: 6.789%
```
虽然 `{{ $values.B }}` 打印数字 6.789，但其实际上是一个字符串，因为您打印的对象同时包含 RefID B 的标签和值，而不是 B 的浮点值。要使用 RefID B 的浮点值，必须使用 `$values.B` 中的 `Value` 字段。如果要对警报摘要中的浮点值进行人性化处理：
```
{{ $labels.service }} has over 5% of responses with 5xx errors: {{ humanize $values.B.Value }}%
```
**无数据、运行时错误和超时**
如果警报规则中的查询未返回任何数据，或者由于数据来源错误或超时而失败，则使用该查询的任何阈值、Reduce 或 Math 表达式也将不返回任何数据或错误。当这种情况发生时，这些表达式将缺失 `$values`。最好在使用 RefID 之前检查 RefID 是否存在，否则，如果您的查询没有返回任何数据或错误，模板将会中断。您可使用 if 语句实现：
```
{{ if $values.B }}{{ $labels.service }} has over 5% of responses with 5xx errors: {{ humanizePercentage $values.B.Value }}{{ end }}
```
## 经典条件
如果规则使用经典条件而不是阈值、Reduce 和 Math 表达式，则 `$values` 变量将由 Ref ID 和条件在经典条件中的位置进行索引。例如，如果您有一个带有 RefID B 的经典条件，其中包含两个条件，则 `$values` 将包含两个条件 `B0` 和 `B1`。
```
The first condition is {{ $values.B0 }}, and the second condition is {{ $values.B1 }}
```
## 函数
在展开标签和注释时，可以使用以下函数：
**args**
`args` 函数将对象列表转换为带有 arg0、arg1 等键的映射。这是为了允许将多个参数传递给模板。
**示例**
```
{{define "x"}}{{.arg0}} {{.arg1}}{{end}}{{template "x" (args 1 "2")}}
```
```
1 2
```
**externalURL**
`externalURL` 函数返回 ini 文件中配置的 Grafana 服务器的外部 URL。
**示例**
```
{{ externalURL }}
```
```
https://example.com/grafana
```
**graphLink**
`graphLink` 函数返回给定表达式和数据来源在 [Grafana 9 中的 Explore](v9-explore.md) 中图形视图的路径。
**示例**
```
{{ graphLink "{\"expr\": \"up\", \"datasource\": \"gdev-prometheus\"}" }}
```
```
/explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":false,"range":true}]
```
**humanize**
`humanize` 函数对十进制数字进行人性化处理。
**示例**
```
{{ humanize 1000.0 }}
```
```
1k
```
**humanize1024**
`humanize1024` 的工作原理类似于 `humanize`，但使用 1024（而不是 1000）作为基数。
**示例**
```
{{ humanize1024 1024.0 }}
```
```
1ki
```
**humanizeDuration**
`humanizeDuration` 函数对持续时间（秒）进行人性化处理。
**示例**
```
{{ humanizeDuration 60.0 }}
```
```
1m 0s
```
**humanizePercentage**
`humanizePercentage` 函数将比率值人性化处理为百分比。
**示例**
```
{{ humanizePercentage 0.2 }}
```
```
20%
```
**humanizeTimestamp**
`humanizeTimestamp` 函数对 Unix 时间戳进行人性化处理。
**示例**
```
{{ humanizeTimestamp 1577836800.0 }}
```
```
2020-01-01 00:00:00 +0000 UTC
```
**match**
`match` 函数将文本与正则表达式模式进行匹配。
**示例**
```
{{ match "a.*" "abc" }}
```
```
true
```
**pathPrefix**
`pathPrefix` 函数返回 ini 文件中配置的 Grafana 服务器的路径。
**示例**
```
{{ pathPrefix }}
```
```
/grafana
```
**tableLink**
`tableLink` 函数返回给定表达式和数据来源在 [Grafana 9 中的 Explore](v9-explore.md) 中表格视图的路径。
**示例**
```
{{ tableLink "{\"expr\": \"up\", \"datasource\": \"gdev-prometheus\"}" }}
```
```
/explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":true,"range":false}]
```
**删除实例快照**
`title` 函数将每个单词的第一个字符大写。
**示例**
```
{{ title "hello, world!" }}
```
```
Hello, World!
```
**toLower**
`toLower` 函数以小写形式返回所有文本。
**示例**
```
{{ toLower "Hello, world!" }}
```
```
hello, world!
```
**toUpper**
`toUpper` 函数以大写形式返回所有文本。
**示例**
```
{{ toUpper "Hello, world!" }}
```
```
HELLO, WORLD!
```
**reReplaceAll**
`reReplaceAll` 函数替换与正则表达式匹配的文本。
**示例**
```
{{ reReplaceAll "localhost:(.*)" "example.com:$1" "localhost:8080" }}
```
```
example.com:8080
```