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 进行排序。稳定排序。 |
first
、label
和 value
函数旨在使查询结果在管道中易于使用。
名称 | 参数 | 返回值 | 注意 |
---|---|---|---|
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 使用,上面列出的函数也是如此。
本文档是开源的。请通过提交问题或拉取请求来帮助改进它。