模板引用

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

数据结构

处理时间序列数据的核心数据结构是 sample，定义为

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

sample 的指标名称在 Labels map 中使用特殊的 __name__ 标签进行编码。

[]sample 表示一个 sample 列表。

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

函数

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

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

查询

名称	参数	返回值	备注
query	查询字符串	[]sample	查询数据库，不支持返回范围向量。
first	[]sample	sample	相当于 `index a 0`
label	label, sample	string	相当于 `index sample.Labels label`
value	sample	interface{}	相当于 `sample.Value`
sortByLabel	label, []samples	[]sample	按给定标签对 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	将比率值转换为 100 的分数。
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	返回表中视图的路径表达式浏览器进行表达式。
parseDuration	string	float	将类似 "1h" 的持续时间字符串解析为它代表的秒数。
stripDomain	string	string	移除 FQDN 的域名部分。保持端口不变。
urlQueryEscape	string	string	url.QueryEscape 对字符串进行转义，使其可以安全地放置在 URL 查询中。

其他

名称	参数	返回值	备注
args	[]interface{}	map[string]interface{}	这会将对象列表转换为一个键为 arg0、arg1 等的 map。目的是允许将多个参数传递给模板。
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 参数作为 map 在 .Params 中可用。要访问同名的多个 URL 参数，.RawParams 是每个参数的列表值的 map。URL 路径在 .Path 中可用，不包括 /consoles/ 前缀。全局配置的外部标签以 .ExternalLabels 的形式可用。所有这四个都有方便的变量：$rawParams、$params、$path 和 $externalLabels。

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

本页内容