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 | 标签,[]samples | []sample | 按给定的标签对样本进行排序。是稳定的。 |
first
、label
和 value
旨在使查询结果易于在管道中使用。
名称 | 参数 | 返回值 | 备注 |
---|---|---|---|
humanize | 数字或字符串 | 字符串 | 使用 公制前缀 将数字转换为更易读的格式。 |
humanize1024 | 数字或字符串 | 字符串 | 与 humanize 类似,但使用 1024 作为基数而不是 1000。 |
humanizeDuration | 数字或字符串 | 字符串 | 将以秒为单位的持续时间转换为更易读的格式。 |
humanizePercentage | 数字或字符串 | 字符串 | 将比率值转换为 100 的分数。 |
humanizeTimestamp | 数字或字符串 | 字符串 | 将以秒为单位的 Unix 时间戳转换为更易读的格式。 |
toTime | 数字或字符串 | *time.Time | 将以秒为单位的 Unix 时间戳转换为 time.Time。 |
人性化函数旨在为人类消费产生合理的输出,并且不保证在 Prometheus 版本之间返回相同的结果。
名称 | 参数 | 返回值 | 备注 |
---|---|---|---|
title | 字符串 | 字符串 | strings.Title,将每个单词的首字母大写。 |
toUpper | 字符串 | 字符串 | strings.ToUpper,将所有字符转换为大写。 |
toLower | 字符串 | 字符串 | strings.ToLower,将所有字符转换为小写。 |
stripPort | 字符串 | 字符串 | net.SplitHostPort,将字符串拆分为主机和端口,然后仅返回主机。 |
match | 模式,文本 | 布尔值 | regexp.MatchString 测试是否存在未锚定的正则表达式匹配。 |
reReplaceAll | 模式,替换,文本 | 字符串 | Regexp.ReplaceAllString 正则表达式替换,未锚定。 |
graphLink | 表达式 | 字符串 | 返回 表达式浏览器中该表达式的图形视图路径。 |
tableLink | 表达式 | 字符串 | 返回 表达式浏览器中该表达式的表格(“表”)视图路径。 |
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 使用,上述列出的函数也是如此。
该文档是开源的。请通过提交问题或拉取请求来帮助改进它。