text/template 引用告警标签、查询值、关联查询结果和安全的 Sprig 函数,生成 Text 或 Markdown 格式的描述内容。
工作方式
规则触发或恢复时,告警引擎在标签增强完成后渲染模板,渲染结果作为事件的备注描述发送。模板中可以使用下面的常用变量,也可以用.FieldName 访问完整事件。
日常模板建议优先使用
$labels、$values、$value、$relates、$status 和 $checkMode。其他短变量用于高级模板或兼容场景,只有确实需要时再使用。内置变量
示例:
查询结果附加信息
如果主查询明确配置了标签字段,其他非值字段会作为附加信息进入$annotations。查询附加信息的 key 为 $<查询名称>.<字段名称>,详见查询结果字段映射:
$ 前缀专门用于查询字段,规则中手工配置的自定义字段名称不能以 $ 开头。字段如何分类,请参见查询结果字段映射。
自定义字段
规则上配置的自定义字段会进入告警事件的$annotations,字段值本身也支持变量与模板渲染:
- 简单变量:支持
${label_name}形式(如${service}),渲染时替换为告警事件中对应标签的值。例如值填写https://a.com/runbook/${service},${service}会被替换为告警事件的service标签值。 - Go template:当值中包含
{{时,整个值按与备注描述相同的 Go template 规则渲染,可以引用本文档介绍的内置变量与函数。 - title 字段:字段名为
title时,其渲染结果将作为事件标题。
runbook_url)。控制台会校验这条规则,不合规范的字段名无法保存。$ 开头的名称保留给查询产生的字段,不能用作自定义字段名。
示例:
根对象字段
除上面的常用变量外,还可以用.FieldName 访问以下事件字段:
关联查询结果行
关联查询结果通过$relates 访问。map 的 key 是关联查询名称,例如 R1。
示例:
在恢复通知中显示恢复时的数值
告警恢复时,备注描述和自定义字段(含title)会重新渲染一次,此时 $status 为 recovered。$values 中是哪一次检测的数值,取决于检测方式和恢复方式。
各恢复方式下的数值
使用恢复查询的两种方式中,如果恢复时主查询仍能查到该告警对象,主查询数值是恢复时的数值,否则是最近一次告警或重复通知时的数值。恢复查询只用于判断是否恢复,查询结果不提供给模板。需要在恢复通知中展示其他数值时,请使用关联查询。
存在多个数值时
$value 为 0。规则有多个查询或查询返回多个值字段时,请用 getvalue $values "<key>" 按 key 读取。阈值判定:直接引用查询值
使用前两种恢复方式时,在模板中按$status 分支,引用同一个 key 即可。下例中主查询 A 返回 CPU 使用率:
数据存在:用关联查询获取恢复时的数值
使用“查询检测查不到数据即恢复”时,恢复这一次检测没有查到数据,$values 只能提供最近一次通知时的数值。需要恢复时的数值,请使用关联查询:每次发送通知(包括恢复通知)时都会执行一次关联查询,与检测方式和恢复方式无关。在关联查询中查询需要展示的数值,然后在模板中通过 $relates 引用。
SQL 类数据源的关联查询结果以文本形式返回,请用 $row.Field "<列名>" 读取。
关联查询示例:主查询按 service 检测错误日志,关联查询 R1 统计最近 5 分钟的错误数。
Go Template 内置函数
以下函数由 Gotext/template 提供。
告警引擎自定义函数
以下函数由告警引擎注册,使用时不需要前缀。Sprig 函数
告警引擎使用 Sprig 标准函数名注册安全的 Sprig 函数,同时也注册sprig_ 前缀形式;标准函数名与自定义函数重名时,自定义函数保留标准函数名,Sprig 函数仍可通过 sprig_ 前缀调用。Sprig 函数来自 Masterminds/sprig;
需要查看上游函数行为时,可以参考该仓库文档。
常用示例:
regexFind 和 sprig_regexFind 返回的是完整匹配文本,不返回捕获组。如果要提取捕获组,请使用 regexReplaceAll 或 sprig_regexReplaceAll:
常用 Sprig 函数
禁用的 Sprig 函数
为了保证渲染结果可预测且安全,读取环境变量、DNS 解析、生成随机数、创建证书或密钥、加解密、会让模板主动失败的 Sprig 函数不可用(如env、expandenv、getHostByName、bcrypt、genPrivateKey、encryptAES、uuidv4、randAlphaNum、fail),标准形式和 sprig_ 前缀形式都不可用。模板使用这些函数时会报类似 function "env" not defined 的错误,请删除该函数,或改用确定性的模板逻辑。
完整示例:提取 MySQL Unknown Column 字段名
排障
function "contains" not defined 表示告警引擎版本过低,尚未启用 Sprig 标准函数名。请升级告警引擎,或临时改用 sprig_contains。
function "env" not defined 表示模板使用了被禁用的 Sprig 函数,见上文禁用的 Sprig 函数。
regexFind 或 sprig_regexFind 返回 Unknown column 'x' 而不是 x 是预期行为。提取捕获组请使用 regexReplaceAll 或 sprig_regexReplaceAll。