基于 Go 模板语言的 Prometheus 模板语法 | 鹏之背

date

related_level

slug

prometheus_template

type

Post

relate_date

summary

Prometheus 模板基于 Go template，用于告警与控制台，支持查询、条件、格式化及丰富函数，统一处理样本数据并安全渲染可视化页面

status

Published

category

编程开发

last_updated

Jan 10, 2026 07:13 PM

是否已更新

orginal_page

是否推荐

参考资料

https://prometheus.io/docs/prometheus/latest/configuration/template_examples/

https://prometheus.io/docs/visualization/consoles/

https://prometheus.io/docs/prometheus/latest/configuration/template_reference/

模板具备对本地数据库执行查询、遍历数据、使用条件语句、格式化数据等功能

支持在告警的 annotations 字段中以及控制台页面（console pages）中使用模板

控制台页面通过 /consoles/ 路径对外提供，其模板文件来自由 -web.console.templates 命令行参数所指定的目录

控制台模板使用 Go 的 html/template 包进行渲染，该包默认启用自动 HTML 转义（auto-escaping）以增强安全性

如需输出原始 HTML 内容（例如嵌入图表或链接），请使用 safe* 系列函数（如 safeHtml）来绕过自动转义

数据结构：样本（sample）

处理时间序列数据的主要数据结构是样本（sample）

样本的指标名称（metric name）编码在 Labels 映射中的一个特殊标签 __name__ 中

Go 中的 interface{} 类似于 C 语言中的 void* 指针，可表示任意类型

[]sample 表示一个样本列表

除了 Go 模板系统自带的默认函数外，Prometheus 还提供了一系列额外函数

如果在管道（pipeline）中使用这些函数，管道中的当前值将作为最后一个参数传入函数

查询相关函数

函数名	参数	返回值	说明
`query`	查询字符串（query string）	`[]sample`	对数据库执行即时向量查询；不支持返回范围向量（range vectors）。
`first`	`[]sample`	`sample`	等价于 `index a 0`，返回样本列表中的第一个元素。
`label`	标签名（string）、`sample`	`string`	等价于 `sample.Labels[label]`，获取样本中指定标签的值。
`value`	`sample`	`interface{}`	等价于 `sample.Value`，获取样本的数值。
`sortByLabel`	标签名（string）、`[]sample`	`[]sample`	按指定标签对样本列表进行稳定排序。

数值格式化函数

函数名	参数	返回值	说明
`humanize`	number or string	string	使用公制前缀（如 k、M、G）将数字转换为更易读的格式（以 1000 为基数）
`humanize1024`	number or string	string	类似 `humanize`，但使用 1024 为基数（适用于 KiB、MiB 等）
`humanizeDuration`	number or string	string	将以秒为单位的持续时间转换为易读格式（如 "2h3m5s"）
`humanizePercentage`	number or string	string	将比率（如 0.75）转换为百分比形式（如 "75%"）
`humanizeTimestamp`	number or string	string	将 Unix 时间戳（秒）转换为人类可读的时间格式（如 "2025-01-01 12:00:00 UTC"）
`toTime`	number or string	`*time.Time`	将 Unix 时间戳（秒）转换为 Go 的 `time.Time` 类型
`toDuration`	number or string	`*time.Duration`	将以秒为单位的数值转换为 Go 的 `time.Duration` 类型
`now`	无	float64	返回模板求值时的 Unix 时间戳（单位：秒）

字符串处理函数

函数名	参数	返回值	说明
`title`	string	string	使用 `cases.Title`，将每个单词的首字母大写（如 "hello world" → "Hello World"）。
`toUpper`	string	string	使用 `strings.ToUpper`，转为全大写。
`toLower`	string	string	使用 `strings.ToLower`，转为全小写。
`stripPort`	string	string	使用 `net.SplitHostPort`，从 "host:port" 中提取主机部分（如 "example.com:9090" → "example.com"）。
`match`	pattern（regex）、text	boolean	使用 `regexp.MatchString`，测试文本是否匹配非锚定正则表达式。
`reReplaceAll`	pattern、replacement、text	string	使用 `Regexp.ReplaceAllString` 执行非锚定正则替换。
`graphLink`	PromQL expr	string	返回该表达式在 Prometheus 表达式浏览器中的图形视图路径。
`tableLink`	PromQL expr	string	返回该表达式在表达式浏览器中的表格视图（"Table"）路径。
`parseDuration`	string（如 "1h30m"）	float	将持续时间字符串解析为对应的秒数（如 "1h" → 3600.0）。
`stripDomain`	string	string	移除 FQDN 的域名部分，仅保留主机名和端口（→ "host:8080"）。
`urlQueryEscape`	string	string	使用 `url.QueryEscape` 对字符串进行 URL 查询转义。

其他函数

函数名	参数	返回值	说明
`args`	`[]interface{}`	`map[string]interface{}`	将参数列表转换为键为 `arg0`, `arg1`... 的映射，便于向模板传递多个参数。
`tmpl`	模板名（string）、参数列表（`[]interface{}`）	无	类似内置 `template` 函数，但允许模板名为变量（非字面量）。结果被视为安全 HTML，不会自动转义。仅在控制台模板中可用。
`safeHtml`	string	string	将字符串标记为安全 HTML，跳过自动转义。
`externalURL`	无	string	返回 Prometheus 实例对外可访问的外部 URL。
`pathPrefix`	无	string	返回用于控制台模板的外部 URL 路径前缀。

模板类型差异：告警字段模板，控制台模板

告警字段模板

在告警的标签（labels）和注解（annotations）中使用的模板可访问以下变量：

.Value：当前告警实例的数值（即 PromQL 表达式的计算结果）
.Labels：该告警实例的标签集合（map[string]string）
.ExternalLabels：Prometheus 全局配置的外部标签（external labels）。
.ExternalURL：Prometheus 的外部访问 URL（通过 -web.external-url 参数配置）

这些变量也会通过以下全局变量形式暴露

$value
$labels
$externalLabels
$externalURL

控制台模板

在控制台模板可访问以下变量：

.Params：一个 map，包含所有 URL 查询参数。对于重复的参数名，仅保留最后一个值
.RawParams：一个 map，其中每个键对应一个字符串切片（[]string），保留了所有同名 URL 参数的完整值列表
.Path：当前请求的 URL 路径（不包含 /consoles/ 前缀）
.ExternalLabels：Prometheus 全局配置的外部标签（external labels）

这些变量也会通过以下全局变量形式暴露

$rawParams
$params
$path
$externalLabels

console templates 样例

prom_right_table_head 和 prom_right_table_tail 模板包含右侧表格

显示了任务数量、正在运行的任务数量、平均 CPU 使用率和平均内存使用率

prom_query_drilldown 模板会计算传递给它的表达式，对其进行格式化，并链接到表达式浏览器中的该表达式

显示了每秒查询次数图表

通过 console library 定义可重用的模板

控制台模板可以调用位于 -web.console.libraries 指定目录下、所有 *.lib 文件中通过 {{define "templateName"}}...{{end}} 定义的共享模板

所有 *.lib 文件共享同一个模板命名空间，请注意避免与其他用户定义的模板名称发生冲突

以下命名规则为 Prometheus 保留，禁止用于自定义模板或函数

模板名称以 prom、_prom 或 __ 开头
文档中列出的所有内置函数（如 query、humanize、safeHtml 等）

可重用的模板样例 myTemplate

模板只能接受一个参数，可以使用 args 函数来包装多个参数

白鸟3