模板参考

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

数据结构

处理时间序列数据的主要数据结构是样本 (sample)，定义如下：

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

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

[]sample 表示一个样本列表。

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

函数

除了 Go 模板提供的默认函数外，Prometheus 还提供了一些函数，以便在模板中更轻松地处理查询结果。

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

查询

名称	参数	返回值	备注
query	查询字符串	[]sample	查询数据库，不支持返回范围向量 (range vectors)。
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。
toDuration	数字或字符串	*time.Duration	将以秒为单位的持续时间转换为 time.Duration。
now	无	float64	返回模板执行时刻的 Unix 时间戳（秒）。

人性化 (Humanizing) 函数旨在产生适合人类阅读的输出，不保证在不同 Prometheus 版本间返回完全相同的结果。

字符串

名称	参数	返回值	备注
title	字符串	字符串	cases.Title ，将每个单词的首字母大写。
toUpper	字符串	字符串	strings.ToUpper ，将所有字符转换为大写。
toLower	字符串	字符串	strings.ToLower ，将所有字符转换为小写。
stripPort	字符串	字符串	net.SplitHostPort ，将字符串拆分为主机和端口，仅返回主机部分。
match	模式，文本	布尔值	regexp.MatchString 测试非锚定的正则表达式匹配。
reReplaceAll	模式，替换值，文本	字符串	Regexp.ReplaceAllString 正则表达式替换，非锚定。
graphLink	expr	字符串	返回表达式浏览器中用于该表达式的图形视图路径。
tableLink	expr	字符串	返回表达式浏览器中用于该表达式的表格视图路径。
parseDuration	字符串	浮点数	将如 "1h" 的持续时间字符串解析为代表的秒数。
stripDomain	字符串	字符串	移除 FQDN 的域名部分。端口保持不变。
urlQueryEscape	字符串	字符串	url.QueryEscape 转义字符串，以便可以安全地放入 URL 查询中。

其他

名称	参数	返回值	备注
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 保留使用。

本页内容