跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.flashcat.cloud/llms.txt

Use this file to discover all available pages before exploring further.

Monitors 告警规则的 备注描述（Description） 用于定义告警和恢复事件中的说明文本。你可以使用 Go text/template 引用告警标签、查询值、关联查询结果和安全的 Sprig 函数，生成 Text 或 Markdown 格式的描述内容。
本文描述的模板变量、Sprig 函数名和标签增强后再渲染 Description 的行为需要 monit-edge v0.42.0 或以上版本。低于该版本时，部分变量或函数可能不可用，标签增强结果也可能无法在备注模板中引用。

​
工作方式

规则触发或恢复时，monit-edge 会把完整告警事件作为模板根对象，并额外注入一组常用短变量。标签增强执行完成后，模板会基于增强后的事件渲染，结果会写入事件的 Description 字段，再继续发送事件。
日常模板建议优先使用 $labels、$values、$value、$relates、$status 和 $checkMode。其他短变量用于高级模板或兼容场景，只有确实需要时再使用。

​
Sprig 函数名

monit-edge 会使用 Sprig 标准函数名注册安全的 Sprig 函数。同一个可用函数也会额外注册一份 sprig_ 前缀形式，方便在命名冲突时使用。 应该这样写： 
{{ contains "Unknown column" $msg }}
{{ regexMatch "Unknown column" $msg }}
{{ regexFind "Unknown column '[^']+'" $msg }}
也可以使用带前缀的形式： 
{{ sprig_contains "Unknown column" $msg }}
{{ sprig_regexMatch "Unknown column" $msg }}
{{ sprig_regexFind "Unknown column '[^']+'" $msg }}
如果 Sprig 标准函数名与 monit-edge 自定义函数重名，monit-edge 自定义函数会保留标准函数名，Sprig 函数仍可通过 sprig_ 前缀调用。

​
内置变量

变量类型说明
$labelsmap[string]string告警标签，与 .DataLabels 相同。
$valuesmap[string]float64告警计算中使用到的数值，与 .Values 相同。
$valuefloat64主告警值，与 .Value 相同。
$appendLabelsmap[string]string规则上配置的附加标签。
$annotationsmap[string]string规则自定义字段。
$dsTypestring数据源类型。
$dsNamestring数据源名称。
$dsAddressstring数据源地址，不包含认证信息。
$checkModestring检测模式。
$relatesmap[string][]*ResultRow关联查询结果行。
$statusstringfiring 或 recovered。
$severitystring告警级别。
示例： 
{{- if eq $status "firing" }}
规则 {{ .RuleName }} 在 {{ $dsName }} 上触发，当前值：{{ printf "%.2f" $value }}
{{- else }}
规则 {{ .RuleName }} 已恢复。
{{- end }}

​
根对象字段

根对象字段使用 .FieldName 访问。
字段类型说明
.Hashstring稳定的事件 hash。同一个事件的告警和恢复使用相同 hash。
.DataSourceTypestring数据源类型。
.DataSourceNamestring数据源名称。
.DataSourceAddressstring数据源地址，不包含认证信息。
.RuleNamestring告警规则名称。
.RuleIDuint64告警规则 ID。
.Queries[]Query规则查询定义。
.RelateQueries[]RelateQuery关联查询定义。
.CheckModestring检测模式。
.DataLabelsmap[string]string告警标签。
.AppendLabelsmap[string]string规则上配置的附加标签。
.EnrichLabelsmap[string]string外部标签增强接口返回的标签。标签增强会先于 Description 渲染执行，因此模板可以引用这些标签。
.Valuesmap[string]float64告警计算中使用到的数值。
.Annotationsmap[string]string规则自定义字段。
.Relatesmap[string][]*ResultRow关联查询结果行。
.Statusstringfiring 或 recovered。
.Severitystring告警级别。
.EvalTimeint64本次评估时间，Unix 秒级时间戳。
.Descriptionstring渲染后的描述。该字段在模板执行完成后才设置。
.DescriptionTypestring描述类型，例如 text 或 markdown。
.Valuefloat64主告警值。
.TitleRulestringedge 上配置的标题规则。
.Queries 中的 Query 对象包含 .Name、.Expr、.LabelFields、.ValueFields 和 .Args。 .RelateQueries 中的 RelateQuery 对象包含 .Name、.Expr 和 .Args。

​
关联查询结果行

关联查询结果通过 $relates 访问。map 的 key 是关联查询名称，例如 R1。
字段或方法类型说明
$row.Fieldsmap[string]interface{}关联查询返回的非数值字段或展示字段。
$row.Valuesmap[string]float64关联查询返回的数值字段。
$row.Field "name"interface{}从 $row.Fields 读取一个字段。
$row.Valuefloat64返回 $row.Values 中的第一个数值；如果没有数值则返回 NaN。
$row.Value "name"float64从 $row.Values 读取一个数值；如果 key 不存在则返回 NaN。
$row.Stringstring返回该行的调试字符串。
示例： 
{{- range $row := $relates.R1 }}
- 日志：{{ $row.Field "_msg" }}
- 次数：{{ printf "%.0f" ($row.Value "count") }}
{{- end }}

​
Go Template 内置函数

以下函数由 Go text/template 提供。
函数说明示例
and逻辑 AND。结果确定后停止继续求值。{{ if and $a $b }}yes{{ end }}
or逻辑 OR。结果确定后停止继续求值。{{ if or $a $b }}yes{{ end }}
not逻辑 NOT。{{ if not $ok }}failed{{ end }}
eq等于。{{ if eq $status "firing" }}...{{ end }}
ne不等于。{{ if ne $severity "Info" }}...{{ end }}
lt小于。{{ if lt $value 10.0 }}...{{ end }}
le小于等于。{{ if le $value 10.0 }}...{{ end }}
gt大于。{{ if gt $value 10.0 }}...{{ end }}
ge大于等于。{{ if ge $value 10.0 }}...{{ end }}
index从 map、slice 或 array 中读取元素。{{ index $labels "instance" }}
slice对字符串、slice 或 array 做切片。{{ slice "abcdef" 0 3 }}
len返回长度。{{ len $relates.R1 }}
printf使用 fmt.Sprintf 语法格式化文本。{{ printf "%.2f" $value }}
print使用默认格式拼接多个值。{{ print $dsName ":" $status }}
println类似 print，但会追加换行。{{ println $dsName }}
call调用函数值。Description 中通常很少使用。{{ call .SomeFunc }}
html按 HTML 规则转义文本。{{ html $text }}
js按 JavaScript 规则转义文本。{{ js $text }}
urlquery按 URL query 规则转义文本。{{ urlquery $text }}

​
monit-edge 自定义函数

以下函数由 monit-edge 注册，使用时不需要前缀。
函数说明示例
pathEscape text对 URL path 做转义。{{ pathEscape "a/b c" }}
queryEscape text对 URL query 做转义。{{ queryEscape "level=error msg" }}
getvalue values key [format]从 map[string]float64 中读取数值并格式化。默认格式是 %.4f。如果 key 为空或不存在，会返回 template_function_error: ... 文本。{{ getvalue $values "$A" "%.2f" }}
getfvalue values key从 map[string]float64 中读取数值。如果 key 为空或不存在，返回 NaN。{{ if gt (getfvalue $values "$A") 10.0 }}high{{ end }}
trunc count texttruncRune 的别名。按 Unicode 字符截断，不按字节截断。count 为负数时从末尾保留字符。{{ trunc 10 $msg }}
truncRune count text按 Unicode 字符截断。{{ truncRune -8 "abcdef你好" }}
runeCount text统计 Unicode 字符数。{{ runeCount "你好abc" }}
args ...构造一个 map，key 为 arg0、arg1 等。{{ args "a" 1 }}
reReplaceAll pattern repl text正则替换。参数顺序是 pattern、replacement、text。正则非法时会导致模板渲染失败。{{ reReplaceAll ".*id=([0-9]+).*" "$1" $msg }}
safeHtml text将文本转换为 html/template.HTML 类型。Description 使用 text/template 渲染，该函数不会清洗 HTML，也不会改变转义行为。普通 text 或 Markdown 不建议使用。{{ safeHtml "<b>OK</b>" }}
match pattern text正则匹配，等价于 Go regexp.MatchString。正则非法时会导致模板渲染失败。{{ if match "Unknown column" $msg }}...{{ end }}
toUpper text转成大写。{{ toUpper $severity }}
toLower text转成小写。{{ toLower $status }}
stripPort hostPort从 host:port 中去掉端口。如果解析失败，返回原始值。{{ stripPort "example.com:9100" }}
stripDomain hostPort去掉主机名中的域名后缀，并保留端口。IP 地址会原样返回。{{ stripDomain "node01.prod.local:9100" }}
humanize value使用 SI 单位格式化数字。{{ humanize 12345 }}
humanize1024 value使用 1024 进制单位格式化数字。{{ humanize1024 1048576 }}
humanizeDuration seconds将秒数格式化为可读时长。{{ humanizeDuration 3661 }}
humanizePercentage value将比例格式化为百分比。{{ humanizePercentage 0.1234 }}
humanizeTimestamp seconds将 Unix 秒级时间戳转为 UTC 时间文本。{{ humanizeTimestamp .EvalTime }}
toTime seconds将 Unix 秒级时间戳转为 time.Time。{{ (toTime .EvalTime).Format "2006-01-02 15:04:05" }}
nanoTime value [tzOffset]将 Unix 纳秒级时间戳转为 time.Time。可选时区偏移单位为小时。{{ (nanoTime $row.Fields.__time__ 8).Format "2006-01-02 15:04:05" }}
timeFormat value format [tzOffset]格式化 time.Time、*time.Time、RFC3339 字符串或 RFC3339Nano 字符串。可选时区偏移单位为小时。{{ timeFormat "2026-01-06T11:48:12Z" "2006-01-02 15:04:05" 8 }}
parseDuration duration解析时长字符串并返回秒数。{{ parseDuration "5m" }}
add a b数值加法。{{ add 1 2 }}
sub a b数值减法。{{ sub 10 3 }}
mul a b数值乘法。{{ mul $value 100 }}
div a b数值除法。除零会导致模板渲染失败。{{ div $value 1024 }}
now当前时间，类型为 time.Time。{{ now.Format "2006-01-02 15:04:05" }}
toString value使用 fmt.Sprint 将值转为字符串。{{ toString $row.Fields._msg }}

​
Sprig 函数

monit-edge 会使用 Sprig 标准函数名注册安全的 Sprig 函数，同时也注册 sprig_ 前缀形式。Sprig 函数来自 Masterminds/sprig； 需要查看上游函数行为时，可以参考该仓库文档。 常用示例： 
{{ contains "error" $msg }}
{{ regexMatch "Unknown column" $msg }}
{{ regexFind "Unknown column '[^']+'" $msg }}
正则使用注意事项：regexFind 和 sprig_regexFind 返回的是完整匹配文本，不返回捕获组。如果要提取捕获组，请使用 regexReplaceAll 或 sprig_regexReplaceAll： 
{{- $msg := "Unknown column 'community_posts.comment_count' in 'field list'" }}
{{- regexReplaceAll ".*Unknown column '([^']+)'.*" $msg "$1" }}
结果是： 
community_posts.comment_count

​
常用 Sprig 函数

函数说明示例
contains substr text判断 text 是否包含 substr。{{ if contains "Unknown column" $msg }}...{{ end }}
hasPrefix prefix text判断前缀。{{ hasPrefix "prod-" $name }}
hasSuffix suffix text判断后缀。{{ hasSuffix ".log" $file }}
regexMatch pattern text正则匹配。{{ regexMatch "error|failed" $msg }}
regexFind pattern text返回第一个完整正则匹配。{{ regexFind "trace_id=[a-z0-9]+" $msg }}
regexFindAll pattern text n返回最多 n 个完整正则匹配。-1 表示全部返回。{{ regexFindAll "id=[0-9]+" $msg -1 }}
regexReplaceAll pattern text repl正则替换。参数顺序是 pattern、text、replacement。{{ regexReplaceAll ".*id=([0-9]+).*" $msg "$1" }}
trim text去掉首尾空白字符。{{ trim $msg }}
lower text转小写。{{ lower $severity }}
upper text转大写。{{ upper $severity }}
default default value当 value 为空时使用默认值。{{ default "unknown" (index $labels "instance") }}
toJson value将值转为 JSON。{{ toJson $labels }}
dict ...创建字典。{{ dict "name" $dsName "status" $status }}
list ...创建列表。{{ list "a" "b" "c" }}
同一个函数也可以使用 sprig_ 前缀调用，例如 sprig_contains 和 sprig_regexReplaceAll。

​
禁用的 Sprig 函数

为了保证告警描述渲染过程可预测且安全，monit-edge 不会注册会读取进程环境变量、执行 DNS 解析、生成随机输出、创建凭证或证书、加解密数据，或者主动让模板失败的 Sprig 函数。 以下 Sprig 函数的标准形式和 sprig_ 前缀形式都不可用： 
env / sprig_env
expandenv / sprig_expandenv
getHostByName / sprig_getHostByName
bcrypt / sprig_bcrypt
htpasswd / sprig_htpasswd
derivePassword / sprig_derivePassword
genPrivateKey / sprig_genPrivateKey
buildCustomCert / sprig_buildCustomCert
genCA / sprig_genCA
genCAWithKey / sprig_genCAWithKey
genSelfSignedCert / sprig_genSelfSignedCert
genSelfSignedCertWithKey / sprig_genSelfSignedCertWithKey
genSignedCert / sprig_genSignedCert
genSignedCertWithKey / sprig_genSignedCertWithKey
encryptAES / sprig_encryptAES
decryptAES / sprig_decryptAES
randBytes / sprig_randBytes
uuidv4 / sprig_uuidv4
randAlphaNum / sprig_randAlphaNum
randAlpha / sprig_randAlpha
randAscii / sprig_randAscii
randNumeric / sprig_randNumeric
randInt / sprig_randInt
shuffle / sprig_shuffle
fail / sprig_fail
如果模板使用这些函数，解析阶段会报类似 function "env" not defined 或 function "sprig_env" not defined 的错误。

​
完整示例：提取 MySQL Unknown Column 字段名

{{- if eq $status "firing" }}
在过去5分钟的时间内，数据库操作出现缺失字段错误 {{ $value | printf "%.0f" }} 次；
{{- range $x := $relates.R1 }}
  {{- $msg := printf "%v" ($x.Field "_msg") }}
  {{- if contains "Unknown column" $msg }}
    {{- $field := regexReplaceAll ".*Unknown column '([^']+)'.*" $msg "$1" }}

- 缺失字段：{{ $field }}
- 查看地址：https://example.com/logs?query={{ queryEscape "Unknown column" }}
  {{- end }}
{{- end }}
{{- else }}
数据库缺字段错误已恢复
{{- end }}

​
排障

function "contains" not defined 表示规则运行在较旧的 monit-edge 版本上，该版本尚未启用 Sprig 标准函数名。请升级 monit-edge；如果该版本支持前缀形式，也可以临时改用 sprig_contains。 function "env" not defined 或 function "sprig_env" not defined 表示模板使用了被禁用的 Sprig 函数。请删除该函数，或改用确定性的模板逻辑。 regexFind 或 sprig_regexFind 返回 Unknown column 'x' 而不是 x 是预期行为。提取捕获组请使用 regexReplaceAll 或 sprig_regexReplaceAll。