模板参考

Prometheus 支持在告警的注释(annotations)和标签(labels)中以及在服务的控制台页面中使用模板。模板能够对本地数据库运行查询、迭代数据、使用条件语句、格式化数据等。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 按给定 label 对 samples 进行排序。稳定排序。

firstlabelvalue 函数旨在使查询结果在管道中易于使用。

数字

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

Humanizing 函数旨在生成供人类消费的合理输出,但不保证在不同 Prometheus 版本之间返回相同的结果。

字符串

名称 参数 返回值 注意
title string string cases.Title,将每个单词的首字母大写。
toUpper string string strings.ToUpper,将所有字符转换为大写。
toLower string string strings.ToLower,将所有字符转换为小写。
stripPort string string net.SplitHostPort,将字符串分割为 host 和 port,然后只返回 host。
match 模式, 文本 布尔值 regexp.MatchString 测试非锚定的正则表达式匹配。
reReplaceAll 模式, 替换文本, 文本 string Regexp.ReplaceAllString 正则表达式替换,非锚定。
graphLink expr string 返回表达式在表达式浏览器中的图形视图路径。
tableLink expr string 返回表达式在表达式浏览器中的表格("Table")视图路径。
parseDuration string 浮点数 解析持续时间字符串(例如 "1h")为表示的秒数。
stripDomain string string 移除 FQDN 的域名部分。保留 port 不变。

其他

名称 参数 返回值 注意
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 参数在 .Params 中作为 map 可用。要按相同名称访问多个 URL 参数,.RawParams 是每个参数列表值的 map。URL 路径在 .Path 中可用,不包括 /consoles/ 前缀。全局配置的外部标签作为 .ExternalLabels 可用。还有四个方便变量:$rawParams$params$path$externalLabels

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

本文档是开源的。请通过提交问题或拉取请求来帮助改进它。