> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 备注模板

> 配置 Monitors 告警规则备注描述的 Go Template 变量、关联查询结果和 Sprig 函数。

Monitors 告警规则的 **备注描述（Description）** 用于定义告警和恢复事件中的说明文本。您可以使用 Go `text/template` 引用告警标签、查询值、关联查询结果和安全的 Sprig 函数，生成 Text 或 Markdown 格式的描述内容。

> [!WARNING]
>
> 本文描述的模板变量和函数需要告警引擎 `v0.42.0` 或以上版本；通过 `$annotations` 读取 `$<查询名称>.<字段名称>` 格式的查询附加信息需要 `v0.53.0` 或以上版本。

## 工作方式

规则触发或恢复时，告警引擎在标签增强完成后渲染模板，渲染结果作为事件的备注描述发送。模板中可以使用下面的常用变量，也可以用 `.FieldName` 访问完整事件。

> [!NOTE]
>
> 日常模板建议优先使用 `$labels`、`$values`、`$value`、`$relates`、`$status` 和 `$checkMode`。其他短变量用于高级模板或兼容场景，只有确实需要时再使用。

## 内置变量

| 变量 | 类型 | 说明 |
| - | - | - |
| `$labels` | `map[string]string` | 告警标签，与 `.DataLabels` 相同。 |
| `$values` | `map[string]float64` | 告警计算中使用到的数值，与 `.Values` 相同。 |
| `$value` | `float64` | 主告警值，与 `.Value` 相同。 |
| `$appendLabels` | `map[string]string` | 规则上配置的附加标签。使用 Go 模板的附加标签在这里是模板原文，推送前才会渲染，见[附加标签的写法](https://docs.flashduty.com/zh/monitors/quickstart/quickstart.md#append-label-syntax)。 |
| `$annotations` | `map[string]string` | 规则自定义字段和查询结果携带的附加信息。 |
| `$dsType` | `string` | 数据源类型。 |
| `$dsName` | `string` | 数据源名称。 |
| `$dsAddress` | `string` | 数据源地址，不包含认证信息。 |
| `$checkMode` | `string` | 检测模式。 |
| `$relates` | `map[string][]*ResultRow` | 关联查询结果行。 |
| `$status` | `string` | `firing` 或 `recovered`。 |
| `$severity` | `string` | 告警级别。 |

示例：

```gotemplate theme={null}
{{- if eq $status "firing" }}
规则 {{ .RuleName }} 在 {{ $dsName }} 上触发，当前值：{{ printf "%.2f" $value }}
{{- else }}
规则 {{ .RuleName }} 已恢复。
{{- end }}
```

### 查询结果附加信息

如果主查询明确配置了标签字段，其他非值字段会作为附加信息进入 `$annotations`。查询附加信息的 key 为 `$<查询名称>.<字段名称>`，详见[查询结果字段映射](https://docs.flashduty.com/zh/monitors/alert-rules/query-result-fields.md)：

```gotemplate theme={null}
{{ index $annotations "$A.sample_message" }}
{{ index $annotations "$B.sample_message" }}
```

无论只有一个还是多个查询，也无论使用阈值判定、数据存在还是数据缺失模式，写法都相同。`$` 前缀专门用于查询字段，规则中手工配置的自定义字段名称不能以 `$` 开头。字段如何分类，请参见[查询结果字段映射](https://docs.flashduty.com/zh/monitors/alert-rules/query-result-fields.md)。

## 自定义字段

规则上配置的**自定义字段**会进入告警事件的 `$annotations`，字段**值**本身也支持变量与模板渲染：

* **简单变量**：支持 `${label_name}` 形式（如 `${service}`），渲染时替换为告警事件中对应标签的值。例如值填写 `https://a.com/runbook/${service}`，`${service}` 会被替换为告警事件的 `service` 标签值。
* **Go template**：当值中包含 `{{` 时，整个值按与**备注描述**相同的 Go template 规则渲染，可以引用本文档介绍的内置变量与函数。
* **title 字段**：字段名为 `title` 时，其渲染结果将作为**事件标题**。

字段**名**必须以英文字母开头，且只能包含英文字母、数字和下划线（例如 `runbook_url`）。控制台会校验这条规则，不合规范的字段名无法保存。`$` 开头的名称保留给查询产生的字段，不能用作自定义字段名。

示例：

| 字段名 | 字段值 | 渲染结果（假设 `service=payment-api`、`$severity=Critical`） |
| - | - | - |
| `runbook` | `https://a.com/runbook/${service}` | `https://a.com/runbook/payment-api` |
| `title` | `[{{ $severity }}] {{ index $labels "service" }} 告警` | `[Critical] payment-api 告警` |

## 根对象字段

除上面的常用变量外，还可以用 `.FieldName` 访问以下事件字段：

| 字段 | 类型 | 说明 |
| - | - | - |
| `.RuleName` | `string` | 告警规则名称。 |
| `.RuleID` | `uint64` | 告警规则 ID。 |
| `.Hash` | `string` | 稳定的事件 hash。同一个事件的告警和恢复使用相同 hash。 |
| `.Queries` | `[]Query` | 规则查询定义。 |
| `.RelateQueries` | `[]RelateQuery` | 关联查询定义。 |
| `.RenderedTitle` | `string` | 标题的渲染结果。规则自定义字段里配置了 `title` 时以 `title` 的渲染结果为准；否则在告警引擎的标题规则（[`alerter.titleRule`](https://docs.flashduty.com/zh/monitors/engine/engine)）是 Go 模板时取其渲染结果。渲染失败或结果中仍残留 `{{` 时该字段为空，标题回落到默认形式，不会把未渲染的模板原文当作标题。 |
| `.EnrichLabels` | `map[string]string` | 外部标签增强接口返回的标签。标签增强先于备注描述渲染，因此模板可以引用这些标签。 |
| `.EvalTime` | `int64` | 本次评估时间，Unix 秒级时间戳。 |

## 关联查询结果行

关联查询结果通过 `$relates` 访问。map 的 key 是关联查询名称，例如 `R1`。

| 字段或方法 | 类型 | 说明 |
| - | - | - |
| `$row.Fields` | `map[string]interface{}` | 关联查询返回的非数值字段或展示字段。 |
| `$row.Values` | `map[string]float64` | 关联查询返回的数值字段。 |
| `$row.Field "name"` | `interface{}` | 从 `$row.Fields` 读取一个字段。 |
| `$row.Value` | `float64` | 返回 `$row.Values` 中的第一个数值；如果没有数值则返回 `NaN`。 |
| `$row.Value "name"` | `float64` | 从 `$row.Values` 读取一个数值；如果 key 不存在则返回 `NaN`。 |
| `$row.String` | `string` | 返回该行的调试字符串。 |

示例：

```gotemplate theme={null}
{{- range $row := $relates.R1 }}
- 日志：{{ $row.Field "_msg" }}
- 次数：{{ printf "%.0f" ($row.Value "count") }}
{{- end }}
```

## 在恢复通知中显示恢复时的数值

告警恢复时，备注描述和自定义字段（含 `title`）会重新渲染一次，此时 `$status` 为 `recovered`。`$values` 中是哪一次检测的数值，取决于检测方式和**恢复方式**。

### 各恢复方式下的数值

| 检测方式 | 恢复方式 | 恢复通知中 `$values` 的数值 |
| - | - | - |
| **阈值判定** | 未触发任一阈值就算恢复 | 恢复时的数值 |
| **阈值判定** | 结果满足条件才算恢复 | 恢复时的数值，包括恢复表达式额外引用的查询 |
| **阈值判定** | 表达式查到数据就算恢复 | 主查询数值，见下方说明 |
| **数据存在** | 查询检测查不到数据即恢复 | 最近一次告警或重复通知时的数值 |
| **数据存在** | 恢复检测查到数据才恢复 | 主查询数值，见下方说明 |

使用恢复查询的两种方式中，如果恢复时主查询仍能查到该告警对象，主查询数值是恢复时的数值，否则是最近一次告警或重复通知时的数值。恢复查询只用于判断是否恢复，查询结果不提供给模板。需要在恢复通知中展示其他数值时，请使用[关联查询](#recovery-related-query)。

> [!NOTE]
>
> 存在多个数值时 `$value` 为 0。规则有多个查询或查询返回多个值字段时，请用 `getvalue $values "<key>"` 按 key 读取。

### 阈值判定：直接引用查询值

使用前两种恢复方式时，在模板中按 `$status` 分支，引用同一个 key 即可。下例中主查询 A 返回 CPU 使用率：

```gotemplate theme={null}
{{- if eq $status "firing" }}
CPU 使用率 {{ getvalue $values "$A" "%.1f" }}%，超过阈值。
{{- else }}
已恢复，当前 CPU 使用率 {{ getvalue $values "$A" "%.1f" }}%。
{{- end }}
```

### 数据存在：用关联查询获取恢复时的数值

使用“查询检测查不到数据即恢复”时，恢复这一次检测没有查到数据，`$values` 只能提供最近一次通知时的数值。需要恢复时的数值，请使用关联查询：每次发送通知（包括恢复通知）时都会执行一次关联查询，与检测方式和恢复方式无关。在关联查询中查询需要展示的数值，然后在模板中通过 `$relates` 引用。

SQL 类数据源的关联查询结果以文本形式返回，请用 `$row.Field "<列名>"` 读取。

关联查询示例：主查询按 `service` 检测错误日志，关联查询 R1 统计最近 5 分钟的错误数。

```sql theme={null}
SELECT count(*) AS cnt
FROM app_logs
WHERE level = 'ERROR'
  AND service = '${service}'
  AND ts > now() - INTERVAL 5 MINUTE
```

```gotemplate theme={null}
{{- if eq $status "firing" }}
服务 {{ index $labels "service" }} 出现错误日志。
{{- else }}
服务 {{ index $labels "service" }} 已恢复，最近 5 分钟错误数：
{{- range $row := $relates.R1 }} {{ $row.Field "cnt" }}{{ end }}
{{- 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 }}` |

## 告警引擎自定义函数

以下函数由告警引擎注册，使用时不需要前缀。

| 函数 | 说明 | 示例 |
| - | - | - |
| `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 text` | `truncRune` 的别名。按 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 函数

告警引擎使用 Sprig 标准函数名注册安全的 Sprig 函数，同时也注册 `sprig_` 前缀形式；标准函数名与自定义函数重名时，自定义函数保留标准函数名，Sprig 函数仍可通过 `sprig_` 前缀调用。Sprig 函数来自 [Masterminds/sprig](https://github.com/Masterminds/sprig)；
需要查看上游函数行为时，可以参考该仓库文档。

常用示例：

```gotemplate theme={null}
{{ contains "error" $msg }}
{{ regexMatch "Unknown column" $msg }}
{{ regexFind "Unknown column '[^']+'" $msg }}
```

正则使用注意事项：`regexFind` 和 `sprig_regexFind` 返回的是完整匹配文本，不返回捕获组。如果要提取捕获组，请使用 `regexReplaceAll` 或 `sprig_regexReplaceAll`：

```gotemplate theme={null}
{{- $msg := "Unknown column 'community_posts.comment_count' in 'field list'" }}
{{- regexReplaceAll ".*Unknown column '([^']+)'.*" $msg "$1" }}
```

结果是：

```text theme={null}
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 函数

为了保证渲染结果可预测且安全，读取环境变量、DNS 解析、生成随机数、创建证书或密钥、加解密、会让模板主动失败的 Sprig 函数不可用（如 `env`、`expandenv`、`getHostByName`、`bcrypt`、`genPrivateKey`、`encryptAES`、`uuidv4`、`randAlphaNum`、`fail`），标准形式和 `sprig_` 前缀形式都不可用。模板使用这些函数时会报类似 `function "env" not defined` 的错误，请删除该函数，或改用确定性的模板逻辑。

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

```gotemplate theme={null}
{{- 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` 表示告警引擎版本过低，尚未启用 Sprig 标准函数名。请升级告警引擎，或临时改用 `sprig_contains`。

`function "env" not defined` 表示模板使用了被禁用的 Sprig 函数，见上文[禁用的 Sprig 函数](#禁用的-sprig-函数)。

`regexFind` 或 `sprig_regexFind` 返回 `Unknown column 'x'` 而不是 `x` 是预期行为。提取捕获组请使用 `regexReplaceAll` 或 `sprig_regexReplaceAll`。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.