模板参考

Prometheus 支持在告警的注解和标签以及控制台页面中使用模板。模板能够对本地数据库运行查询、遍历数据、使用条件、格式化数据等。Prometheus 模板语言基于 Go 模板系统。

数据结构

处理时间序列数据的主要数据结构是 sample，定义如下：

type sample struct {
  Labels map[string]string
  Value  interface{}
}

样本的指标名称编码在 Labels 映射中的特殊 __name__ 标签中。

[]sample 表示样本列表。

Go 中的 interface{} 类似于 C 中的 void 指针。

函数

除了 Go 模板提供的默认函数外，Prometheus 还提供了用于在模板中更方便地处理查询结果的函数。

如果函数在管道中使用，管道值作为最后一个参数传递。

查询

名称	参数	返回值	说明
query	query string	[]sample	查询数据库，不支持返回范围向量。
first	[]sample	sample	等同于 index a 0
label	label, sample	string	等同于 index sample.Labels label
value	sample	interface{}	等同于 sample.Value
sortByLabel	label, []samples	[]sample	按给定标签对样本排序。排序是稳定的。

first、label 和 value 旨在使查询结果在管道中更容易使用。

数字

名称	参数	返回值	说明
humanize	number or string	string	将数字转换为更易读的格式，使用公制前缀。
humanize1024	number or string	string	类似 humanize，但使用 1024 而不是 1000 作为基数。
humanizeDuration	number or string	string	将以秒为单位的持续时间转换为更易读的格式。
humanizePercentage	number or string	string	将比率值转换为百分比。
humanizeTimestamp	number or string	string	将 Unix 时间戳（秒）转换为更易读的格式。
toTime	number or string	*time.Time	将 Unix 时间戳（秒）转换为 time.Time。
toDuration	number or string	*time.Duration	将以秒为单位的持续时间转换为 time.Duration。
now	none	float64	返回模板评估时的 Unix 时间戳（秒）。

人性化函数旨在为人类消费产生合理的输出，不保证在 Prometheus 版本之间返回相同的结果。

字符串

名称	参数	返回值	说明
title	string	string	cases.Title，将每个单词的首字符大写。
toUpper	string	string	strings.ToUpper，将所有字符转换为大写。
toLower	string	string	strings.ToLower，将所有字符转换为小写。
stripPort	string	string	net.SplitHostPort，将字符串分为主机和端口，然后仅返回主机。
match	pattern, text	boolean	regexp.MatchString 测试非锚定的正则匹配。
reReplaceAll	pattern, replacement, text	string	Regexp.ReplaceAllString 正则替换，非锚定。
graphLink	expr	string	返回表达式浏览器中表达式的图形视图路径。
tableLink	expr	string	返回表达式浏览器中表达式的表格（"Table"）视图路径。
parseDuration	string	float	将持续时间字符串（如 "1h"）解析为它表示的秒数。
stripDomain	string	string	移除 FQDN 的域名部分。端口保持不变。
urlQueryEscape	string	string	url.QueryEscape 转义字符串使其可以安全放入 URL 查询中。

其他

名称	参数	返回值	说明
args	[]interface{}	map[string]interface{}	将对象列表转换为键为 arg0、arg1 等的映射。这旨在允许向模板传递多个参数。
tmpl	string, []interface{}	nothing	类似内置的 template，但允许非字面量作为模板名称。注意结果被假定为安全的，不会被自动转义。仅在控制台中可用。
safeHtml	string	string	标记字符串为不需要自动转义的 HTML。
externalURL	none	string	Prometheus 外部可访问的外部 URL。
pathPrefix	none	string	用于控制台模板的外部 URL 路径。

模板类型差异

每种类型的模板提供不同的信息用于参数化模板，并有一些其他差异。

告警字段模板

.Value、.Labels、.ExternalLabels 和 .ExternalURL 分别包含告警值、告警标签、全局配置的外部标签和外部 URL（通过 --web.external-url 配置）。为方便起见，它们也暴露为 $value、$labels、$externalLabels 和 $externalURL 变量。

控制台模板

控制台在 /consoles/ 上暴露，来源于 -web.console.templates 标志指向的目录。

控制台模板使用 html/template 渲染，提供自动转义。要绕过自动转义，请使用 safe* 函数。

URL 参数在 .Params 中作为映射提供。要通过相同名称访问多个 URL 参数，.RawParams 是每个参数的值列表映射。URL 路径在 .Path 中提供，不包括 /consoles/ 前缀。全局配置的外部标签作为 .ExternalLabels 提供。还有四个便捷变量：$rawParams、$params、$path 和 $externalLabels。

控制台还可以访问在 -web.console.libraries 标志指向的目录中的 *.lib 文件中用 {{define "templateName"}}...{{end}} 定义的所有模板。由于这是共享命名空间，请注意避免与其他用户冲突。以 prom、_prom 和 __ 开头的模板名称保留给 Prometheus 使用，上面列出的函数也是如此。