模板参考

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

数据结构

处理时间序列数据的主要数据结构是样本,定义如下:

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

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

[]sample 表示样本列表。

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

函数

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

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

查询

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

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

数字

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

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

字符串

名称参数返回说明
title字符串字符串cases.Title,将每个单词的首字母大写。
toUpper字符串字符串strings.ToUpper,将所有字符转换为大写。
toLower字符串字符串strings.ToLower,将所有字符转换为小写。
stripPort字符串字符串net.SplitHostPort,将字符串拆分为主机和端口,然后仅返回主机。
match模式,文本布尔值regexp.MatchString 测试非锚定的正则表达式匹配。
reReplaceAll模式,替换内容,文本字符串Regexp.ReplaceAllString 正则表达式替换,非锚定。
graphLinkexpr字符串返回表达式浏览器中该表达式的图形视图路径。
tableLinkexpr字符串返回表达式浏览器中该表达式的表格(“Table”)视图路径。
parseDuration字符串浮点数将持续时间字符串(如 "1h")解析为其表示的秒数。
stripDomain字符串字符串移除 FQDN 的域名部分。端口保持不变。

其他

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

本页内容