模版参考

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

数据结构

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

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

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

[]sample代表样本列表。

在 Go 中，interface{}类似于 C 中的空指针。

函数

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

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

查询

名称	参数	返回类型	注释
query	查询字符串	`[]sample`	查询数据库，不支持返回范围向量。
first	`[]sample`	`sample`	等同于 `index a 0`
label	标签，样本	`string`	等同于 `index sample.Labels label`
value	样本	`interface{}`	等同于 `sample.Value`
sortByLabel	标签，`[]samples`	`[]sample`	按给定标签对样本进行排序。稳定排序。

first、label和value函数旨在让查询结果在流程中更加易于使用。

数字

名称	参数	返回类型	注释
humanize	数字或字符串	`string`	使用指标前缀将数字转换为更可读的格式。
humanize1024	数字或字符串	`string`	类似于 `humanize`，但以 1024 为基数而不是 1000。
humanizeDuration	数字或字符串	`string`	将秒数的持续时间转换为更可读的格式。
humanizePercentage	数字或字符串	`string`	将比率值转换为 100 的分数。
humanizeTimestamp	数字或字符串	`string`	将秒数的 Unix 时间戳转换为更可读的格式。
toTime	数字或字符串	`*time.Time`	将秒数的 Unix 时间戳转换为 time.Time。

人类化函数旨在为人类消费提供合理的输出，并且在不同版本的 Prometheus 中可能不会始终产生相同的输出结果。

字符串

名称	参数	返回类型	注释
title	字符串	`string`	strings.Title，首字母大写每个单词。
toUpper	字符串	`string`	strings.ToUpper，将所有字符转换为大写。
toLower	字符串	`string`	strings.ToLower，将所有字符转换为小写。
stripPort	字符串	`string`	net.SplitHostPort，将字符串拆分为主机和端口，然后仅返回主机。
match	模式，文本	`bool`	regexp.MatchString 对未锚定正则表达式匹配进行测试。
reReplaceAll	模式，替换，文本	`string`	Regexp.ReplaceAllString 正则表达式替换，未锚定。
graphLink	表达式	`string`	返回表达式的图形视图在表达式浏览器中的路径。
tableLink	表达式	`string`	返回表达式的表格（“表”）视图在表达式浏览器中的路径。
parseDuration	字符串	`float`	将类似 “1h” 的持续时间字符串解析为其代表的秒数。
stripDomain	字符串	`string`	删除完全限定域名（FQDN）的域名部分。端口不受影响。

其他

名称	参数	返回类型	注释
args	`[]interface{}`	`map[string]interface{}`	将对象列表转换为具有 arg0、arg1 等键的映射。这旨在允许向模板传递多个参数。
tmpl	字符串，`[]interface{}`	`nothing`	类似于内置的`template`，但允许非字面量作为模板名称。注意，结果被假设为安全的，不会被自动转义。仅在控制台中可用。
safeHtml	字符串	`string`	标记字符串为 HTML，无需自动转义。
externalURL	none	`string`	Prometheus 外部可访问的外部 URL。
pathPrefix	none	`string`	用于控制台模板的路径。

模板类型的差异

每种类型的模板提供了不同的信息，可以用于参数化模板，它们存在一些其他差异。

告警字段模板

.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标志指定目录中找到的所有以{{define "templateName"}}...{{end}}定义的模板的权限。由于这是一个共享命名空间，请小心避免与其他用户发生冲突。模板名称以prom、_prom和__开头的模板由 Prometheus 保留使用，上述列出的函数也是如此。

该文档基于 Prometheus 官方文档翻译而成。