模板化标签和注释

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

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

您可以使用模板在标签和标注中包含来自查询和表达式的数据。例如，您可能希望根据查询的值设置警报的严重性标签，或者在摘要注释中使用查询的实例标签，以便了解哪台服务器的 CPU 使用率较高。

所有模板都应以 text/template 编写。无论您是模板化标签还是注释，都应将每个模板内联写入要模板化的标签或注释中。这意味着您不能在标签和注释之间共享模板，而是需要将模板复制到任何要使用它们的位置。

每当评估警报规则时，都会评估每个模板，并针对每个警报单独评估每个模板。例如，如果您的警报规则具有模板化摘要注释，而警报规则有 10 个触发警报，则模板将执行 10 次，每个警报一次。应尽量避免在模板中进行开销较大的计算。

示例

与其写完整的教程，不text/template, the following examples attempt to show the most common use-cases we have seen for templates. You can use these examples verbatim, or adapt them as necessary for your use case. For more information about how to write text/template如参阅文本/模板文档。

打印所有标签（以逗号分隔）

要打印所有标签（以逗号分隔），请打印 $labels 变量：

{{ $labels }}

例如，给定一个带有标签 alertname=High CPU usage、grafana_folder=CPU alerts 和 instance=server1 的警报，将会打印：

alertname=High CPU usage, grafana_folder=CPU alerts, instance=server1

打印所有标签（每行一个）

要打印所有标签（每行一个），请使用 range 遍历每个键/值对并单独打印。这里 $k 是指名称，$v 时值当前标签的值：

{{ range $k, $v := $labels -}}
{{ $k }}={{ $v }}
{{ end }}

例如，给定一个带有标签 alertname=High CPU usage、grafana_folder=CPU alerts 和 instance=server1 的警报，将会打印：

alertname=High CPU usage
grafana_folder=CPU alerts
instance=server1

打印单个标签

要打印单个标签，请使用带有 $labels 变量的 index 函数：

The host {{ index $labels "instance" }} has exceeded 80% CPU usage for the last 5 minutes

例如，给定一个带有标签 instance=server1 的警报，将会打印：

The host server1 has exceeded 80% CPU usage for the last 5 minutes

打印查询的值

要打印即时查询的值，可使用 index 函数和 $values 变量打印其 Ref ID：

{{ index $values "A" }}

例如，给定一个返回值为 81.2345 的即时查询，将会打印：

81.2345

要打印范围查询的值，必须先使用 reduce 表达式将其从时间序列简化为即时向量。然后，您可以改用 Ref ID 来打印 reduce 表达式的结果。例如，如果 reduce 表达式取 A 的平均值并具有 Ref ID B，则可以编写：

{{ index $values "B" }}

打印查询的 humanize 值

要打印即时查询的 humanize 值，请使用 humanize 函数：

{{ humanize (index $values "A").Value }}

例如，给定一个返回值为 81.2345 的即时查询，将会打印：

81.234

要打印范围查询的 humanize 值，必须先使用 reduce 表达式将其从时间序列简化为即时向量。然后，您可以改用 Ref ID 来打印 reduce 表达式的结果。例如，如果 reduce 表达式取 A 的平均值并具有 Ref ID B，则可以编写：

{{ humanize (index $values "B").Value }}

以百分比形式打印查询的值

要以百分比形式打印即时查询的值，请使用 humanizePercentage 函数：

{{ humanizePercentage (index $values "A").Value }}

此函数期望值是介于 0 和 1 之间的十进制数。如果该值是介于 0 和 100 之间的十进制数，则可以在查询中或使用数学表达式将其除以 100。如果查询是范围查询，必须先使用 reduce 表达式将其从时间序列简化为即时向量。

根据查询的值设置严重性

要根据查询的值设置严重性标签，请使用 if 语句和 greater than 比较函数。在与 $values 比较时，确保使用小数（80.0、50.0、0.0 等），因为 text/template 不支持类型强制转换。您可以在此处找到所有支持的比较函数列表。

{{ if (gt $values.A.Value 80.0) -}}
high
{{ else if (gt $values.A.Value 50.0) -}}
medium
{{ else -}}
low
{{- end }}

根据经典条件打印所有标签

如果使用经典条件，则不能使用 $labels 根据查询打印标签，而必须使用 $values。原因是经典条件会丢弃这些标签以强制执行一维行为（每个警报规则最多一个警报）。如果经典条件未丢弃这些标签，则返回许多时间序列的查询将导致警报在触发和解决之间不断波动，因为每次评估警报规则时标签都会变化。

而 $values 变量包含触发条件下所有时间序列的简化值。例如，如果您有一个警报规则，其查询 A 返回两个时间序列，而经典条件 B 具有两个条件，则 $values 将包含 B0、B1、B2 和 B3。如果经典条件 B 只有一个条件，则 $values 只包含 B0 和 B1。

要打印触发时间序列的所有标签，请使用以下模板（如果正则表达式不同，请确保将正则表达式中的 B 替换为经典条件的 Ref ID）：

{{ range $k, $v := $values -}}
{{ if (match "B[0-9]+" $k) -}}
{{ $k }}: {{ $v.Labels }}{{ end }}
{{ end }}

例如，两个时间序列的经典条件超过单个条件，将会打印：

B0: instance=server1
B1: instance=server2

如果经典条件有两个或多个条件，而时间序列同时超出多个条件，则每个超出的条件都会重复其标签：

B0: instance=server1
B1: instance=server2
B2: instance=server1
B3: instance=server2

如果需要打印唯一标签，则应考虑将警报规则从一维更改为多维。您可以将经典条件替换为 reduce 和 math 表达式来做到这一点。

根据经典条件打印所有值

要打印经典条件中的所有值，请使用前面的示例并将 $v.Labels 替换为 $v.Value：

{{ range $k, $v := $values -}}
{{ if (match "B[0-9]+" $k) -}}
{{ $k }}: {{ $v.Value }}{{ end }}
{{ end }}

例如，两个时间序列的经典条件超过单个条件，将会打印：

B0: 81.2345
B1: 84.5678

如果经典条件有两个或多个条件，并且一个时间序列同时超过多个条件，则 $values 将包含所有条件的值：

B0: 81.2345
B1: 92.3456
B2: 84.5678
B3: 95.6789

变量

在模板化标签和注释时，您可以使用以下变量：

标签变量

$labels 变量包含查询中的所有标签。例如，假设您有一个查询，该查询返回所有服务器的 CPU 使用率；有一个警报规则，当任何服务器在过去 5 分钟内 CPU 使用率超过 80% 时触发。您要在警报中添加摘要注释，提醒您哪台服务器的 CPU 使用率较高。您可以使用 $labels 变量，编写一个模板来打印可读的句子，例如：

CPU usage for {{ index $labels "instance" }} has exceeded 80% for the last 5 minutes

值变量

$value 变量是一个字符串，包含所有即时查询的标签和值；阈值、reduce 和 math 表达式以及警报规则中的经典条件。但不包含范围查询的结果，因为这些查询可以返回 10 到 10000 行或指标。如果是这样，对于特别大的查询，单个警报可能会占用 10 秒 MBs 的内存，而 Grafana 很快就会耗尽内存。

要在摘要中打印 $value 变量，可以这样编写：

CPU usage for {{ index $labels "instance" }} has exceeded 80% for the last 5 minutes: {{ $value }}

内容如下所示：

CPU usage for instance1 has exceeded 80% for the last 5 minutes: [ var='A' labels={instance=instance1} value=81.234 ]

这里 var='A' 指的是 Ref ID A 的即时查询，labels={instance=instance1} 指的是标签，value=81.234 指的是过去 5 分钟内的平均 CPU 使用率。

如果您只想打印部分字符串而不是完整字符串，请使用 $values 变量。其中包含与 $value 相同的信息，但采用的是结构化表，使用起来比编写正则表达式来匹配所需的文本要简单得多。

值变量

该$values变量是一个包含所有即时查询和表达式的标签和浮点值的表，并以其 Ref IDs 为索引。

要打印带有 Ref ID A 的即时查询的值：

CPU usage for {{ index $labels "instance" }} has exceeded 80% for the last 5 minutes: {{ index $values "A" }}

例如，给定一个带有标签 instance=server1 的警报和带有值 81.2345 的即时查询，将会打印：

CPU usage for instance1 has exceeded 80% for the last 5 minutes: 81.2345

如果 Ref ID A 中的查询是范围查询，不是即时查询，则添加一个带有 Ref ID B 的 reduce 表达式，并将 (index $values "A") 替换为 (index $values "B")：

CPU usage for {{ index $labels "instance" }} has exceeded 80% for the last 5 minutes: {{ index $values "B" }}

函数

在模板化标签和注释时，您可以使用以下函数：

args

args 函数将对象列表转换为带有 arg0、arg1 等键的映射。这是为了允许将多个参数传递给模板。

{{define "x"}}{{.arg0}} {{.arg1}}{{end}}{{template "x" (args 1 "2")}}

1 2

externalURL

externalURL 函数返回 Grafana 服务器的外部 URL。

{{ externalURL }}

https://example.com/grafana

graphLink

graphLink 函数返回给定表达式和数据来源在 Grafana 10 中的 Explore 中图形视图的路径。

{{ 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 函数返回 Grafana 服务器的路径。

{{ pathPrefix }}

/grafana

tableLink

tableLink 函数返回给定表达式和数据来源在 Grafana 10 中的 Explore 中表格视图的路径。

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