模板参考
Prometheus 支持在告警的注释和标签以及在提供的控制台页面中使用模板。模板能够对本地数据库运行查询、迭代数据、使用条件判断、格式化数据等。Prometheus 模板语言基于 Go 模板 系统。
数据结构
处理时间序列数据的主要数据结构是样本,定义如下:
type sample struct {
Labels map[string]string
Value interface{}
}
样本的指标名称编码在 Labels
映射中的一个特殊标签 __name__
里。
[]sample
表示样本列表。
Go 中的 interface{}
类似于 C 中的 void 指针。
函数
除了 Go 模板提供的默认函数外,Prometheus 还提供了用于在模板中更轻松地处理查询结果的函数。
如果函数在管道中使用,管道值将作为最后一个参数传递。
查询
名称 | 参数 | 返回 | 说明 |
---|---|---|---|
query | 查询字符串 | []sample | 查询数据库,不支持返回范围向量。 |
first | []sample | sample | 等同于 index a 0 |
label | 标签,样本 | 字符串 | 等同于 index sample.Labels label |
value | sample | interface{} | 等同于 sample.Value |
sortByLabel | 标签,[]样本 | []sample | 按给定标签对样本进行排序。是稳定的。 |
first
、label
和 value
旨在使查询结果在管道中易于使用。
数字
名称 | 参数 | 返回 | 说明 |
---|---|---|---|
humanize | 数字或字符串 | 字符串 | 使用公制前缀将数字转换为更易读的格式。 |
humanize1024 | 数字或字符串 | 字符串 | 与 humanize 类似,但使用 1024 作为基数而不是 1000。 |
humanizeDuration | 数字或字符串 | 字符串 | 将以秒为单位的持续时间转换为更易读的格式。 |
humanizePercentage | 数字或字符串 | 字符串 | 将比率值转换为百分比。 |
humanizeTimestamp | 数字或字符串 | 字符串 | 将以秒为单位的 Unix 时间戳转换为更易读的格式。 |
toTime | 数字或字符串 | *time.Time | 将以秒为单位的 Unix 时间戳转换为 time.Time。 |
toDuration | 数字或字符串 | *time.Duration | 将以秒为单位的持续时间转换为 time.Duration。 |
now | 无 | float64 | 返回模板评估时的 Unix 时间戳(以秒为单位)。 |
人性化函数旨在生成供人类使用的合理输出,不保证在不同 Prometheus 版本之间返回相同的结果。
字符串
名称 | 参数 | 返回 | 说明 |
---|---|---|---|
title | 字符串 | 字符串 | cases.Title,将每个单词的首字母大写。 |
toUpper | 字符串 | 字符串 | strings.ToUpper,将所有字符转换为大写。 |
toLower | 字符串 | 字符串 | strings.ToLower,将所有字符转换为小写。 |
stripPort | 字符串 | 字符串 | net.SplitHostPort,将字符串拆分为主机和端口,然后仅返回主机。 |
match | 模式,文本 | 布尔值 | regexp.MatchString 测试非锚定的正则表达式匹配。 |
reReplaceAll | 模式,替换内容,文本 | 字符串 | Regexp.ReplaceAllString 正则表达式替换,非锚定。 |
graphLink | expr | 字符串 | 返回表达式浏览器中该表达式的图形视图路径。 |
tableLink | expr | 字符串 | 返回表达式浏览器中该表达式的表格(“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 使用,上述函数也是如此。