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

模板化标签和注释

在 Grafana 中，您可以像在 Prometheus 中一样对标签和注释进行模板化。如果您之前使用过 Prometheus，那么应该熟悉 $labels 和 $value 变量，包括警报的标签和值。即使警报不使用 Prometheus 数据来源，您也可以在 Grafana 中使用相同的变量。如果您以前没有使用过 Prometheus，请不要担心，因为本页的其余部分将介绍这些变量以及如何对其模板化。

Go 的模板语言

标签和注释的模板是用 Go 的模板语言 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 中图形视图的路径。

示例

{{ 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 中表格视图的路径。

示例

{{ tableLink "{\"expr\": \"up\", \"datasource\": \"gdev-prometheus\"}" }}

/explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":true,"range":false}]

title

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