模板参考

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

数据结构

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

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

样本的指标名称编码在 Labels map 中的一个特殊 __name__ 标签中。

[]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	按给定标签对样本进行排序。是稳定的。

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

数字

名称	参数	返回	备注
humanize	数字或字符串	string	将数字转换为更易读的格式，使用公制前缀。
humanize1024	数字或字符串	string	类似于 `humanize`，但使用 1024 作为基数而不是 1000。
humanizeDuration	数字或字符串	string	将以秒为单位的持续时间转换为更易读的格式。
humanizePercentage	数字或字符串	string	将比率值转换为百分比。
humanizeTimestamp	数字或字符串	string	将以秒为单位的 Unix 时间戳转换为更易读的格式。
toTime	数字或字符串	*time.Time	将以秒为单位的 Unix 时间戳转换为 `time.Time` 类型。

人性化函数旨在生成供人类阅读的合理输出，但不保证在不同 Prometheus 版本之间返回相同的结果。

字符串

名称	参数	返回	备注
title	string	string	cases.Title，将每个单词的首字母大写。
toUpper	string	string	strings.ToUpper，将所有字符转换为大写。
toLower	string	string	strings.ToLower，将所有字符转换为小写。
stripPort	string	string	net.SplitHostPort，将字符串拆分为主机和端口，然后只返回主机。
match	pattern, text	布尔值	regexp.MatchString 测试非锚定正则表达式匹配。
reReplaceAll	pattern, replacement, text	string	Regexp.ReplaceAllString 正则表达式替换，非锚定。
graphLink	expr	string	返回表达式在表达式浏览器中的图表视图路径。
tableLink	expr	string	返回表达式在表达式浏览器中的表格（“Table”）视图路径。
parseDuration	string	浮点数	解析诸如“1h”之类的持续时间字符串，将其转换为秒数。
stripDomain	string	string	移除 FQDN 的域名部分。端口保持不变。

其他

名称	参数	返回	备注
args	[]interface{}	map[string]interface{}	这将对象列表转换为以 arg0、arg1 等为键的 map。这旨在允许向模板传递多个参数。
tmpl	string, []interface{}	无	类似于内置的 `template`，但允许非字面量作为模板名称。请注意，结果被假定是安全的，并且不会自动转义。仅在控制台中可用。
safeHtml	string	string	将字符串标记为不需要自动转义的 HTML。
externalURL	无	string	Prometheus 外部可访问的 URL。
pathPrefix	无	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 使用。

本页内容