Merge pull request #1063 from flashcatcloud/docs/monitors-append-label-template

docs(monitors): document Go templates in alert rule additional labels

Author: UlricQin

en/monitors/alert-rules/description-template.mdx

@@ -51,7 +51,7 @@ available through the `sprig_` prefix.
 | `$labels` | `map[string]string` | Alert labels. Same data as `.DataLabels`. |
 | `$values` | `map[string]float64` | Numeric values used by alert evaluation. Same data as `.Values`. |
 | `$value` | `float64` | Main alert value. Same data as `.Value`. |
-| `$appendLabels` | `map[string]string` | Extra labels configured on the alert rule. |
+| `$appendLabels` | `map[string]string` | Extra labels configured on the alert rule. Additional labels that use Go templates appear here as raw template text and are rendered only before delivery. See [Additional label syntax](/en/monitors/quickstart/quickstart#append-label-syntax). |
 | `$annotations` | `map[string]string` | Custom rule fields and additional information carried from query results. |
 | `$dsType` | `string` | Data source type. |
 | `$dsName` | `string` | Data source name. |

en/monitors/alert-rules/query-result-fields.mdx

@@ -142,6 +142,37 @@ The `$` prefix identifies query-provided fields. A custom field configured on th
 A No data alert carries the additional information from the last successful result for that alert object. If the query has never returned data, no query-provided additional information is available.
 </Note>
 
+<span id="query-fields-as-labels"></span>
+## Sending additional information as alert labels
+
+Additional information reaches On-call with the `__alert_rule_annotation_` prefix, so channel notification templates, escalation rules, and [Alert pipeline](/en/on-call/integration/alert-integration/alert-pipelines) conditions that match ordinary label names (for example `labels.msg`) can't read it. When you need it, use a Go template in the rule's [Additional Labels](/en/monitors/quickstart/quickstart#append-label-syntax) to turn additional information into ordinary labels.
+
+For example, to group error logs by service and still keep the latest log line in notifications:
+
+```sql
+SELECT service, namespace, COUNT(*) AS value,
+       MAX(datetime) AS datetime,
+       MAX_BY(msg, datetime) AS msg,
+       MAX_BY(trace_id, datetime) AS tid
+FROM error_logs
+WHERE datetime >= NOW() - INTERVAL 1 MINUTE
+GROUP BY service, namespace
+```
+
+Select `service` and `namespace` as label fields, so `msg`, `tid`, and `datetime` become additional information. Then configure these additional labels:
+
+```text
+msg      = {{ index $annotations "$A.msg" }}
+tid      = {{ index $annotations "$A.tid" }}
+datetime = {{ index $annotations "$A.datetime" }}
+```
+
+Each service then produces one alert instance, and the `msg`, `tid`, and `datetime` sent to On-call carry the latest log line for that service. Existing notification templates and escalation rules keep working without changes.
+
+<Note>
+Query-provided additional information requires monit-edge `v0.53.0` or later. Earlier alert engines don't provide it, so templates can't read these values.
+</Note>
+
 ## Query result row limits
 
 Edge limits scheduled alert queries and interactive preview queries separately. The following defaults can be configured independently by the deployer:

en/monitors/quickstart/quickstart.mdx

@@ -76,7 +76,35 @@ The create / edit alert rule page is one form with six sections, from top to bot
 |--------|------|
 | **Group** | The group path of the rule (for example, "Default / Database Alerts"). If the group has been deleted or you cannot access it, go back to the rule list and pick a group again |
 | **Rule Name** | Name of the alert rule; does not support variable references (fixed names facilitate filtering and grouping operations). It must be unique within its group; imports, edits, and moves fail if the target group already contains that name |
-| **Additional Labels** | Similar to `labels` in Prometheus; attached to all alert events for filtering, routing, and inhibition |
+| **Additional Labels** | Similar to `labels` in Prometheus; attached to all alert events for filtering, routing, and inhibition. See below for value syntax |
+
+<span id="append-label-syntax"></span>
+#### Additional label syntax
+
+An additional label value takes one of three forms, depending on its content:
+
+| Form | Example | Handling |
+|------|---------|----------|
+| Plain text or `${label name}` | `team=ops`, `instance=${host}` | The alert engine replaces `${label name}` with the alert label |
+| Go template containing `{{` | `msg={{ index $annotations "$A.msg" }}` | Rendered before delivery to the channel and sent as an ordinary label |
+| Starts with `[TPL]` | `owner=[TPL]{{ .Labels.team }}` | Passed to On-call as is and rendered by On-call. See [Alert pipeline](/en/on-call/integration/alert-integration/alert-pipelines) for the syntax |
+
+Go templates can use these variables:
+
+| Variable | Description |
+|----------|-------------|
+| `$labels` | The alert's data labels, for example `{{ $labels.service }}` |
+| `$annotations` | Query-provided additional information and the rule's custom fields. Query-provided keys use `$<query name>.<field name>` and must be read with `index`, for example `{{ index $annotations "$A.msg" }}`. See [Query result field mapping](/en/monitors/alert-rules/query-result-fields#query-fields-as-labels) |
+| `$values` | Values used in alert evaluation, for example `{{ index $values "$A.value" }}` |
+| `$severity` | Alert severity |
+| `$status` | `firing` or `recovered` |
+
+- Templates support only `if` / `else` plus `index`, `len`, `printf`, `print`, `replace`, `urlquery`, and the comparison and logical functions. `range`, `with`, and `define` aren't supported.
+- A missing key reads as an empty string in `$labels` and `$annotations`, and as `0` in `$values`. A label that renders to an empty string isn't sent.
+- A single value can't mix `${...}` and `{{...}}`.
+- A label that fails to render isn't sent, and the alert event is still delivered. The error goes to the `__alert_rule_label_template_error` label, which you can see in the alert details.
+- Leading and trailing whitespace in label names is trimmed on save, and the trimmed names must be unique. Label names can't start with `__alert_rule_`. All additional labels together are limited to 1,024 characters as JSON, and `job` and `instance` values to 255 characters.
+- When the alert engine renders descriptions, custom fields, and titles, template labels in `$appendLabels` are still the raw template text. To use query results there, reference `$annotations` directly.
 
 ### Data sources and queries
 

zh/monitors/alert-rules/description-template.mdx

@@ -47,7 +47,7 @@ monit-edge 会使用 Sprig 标准函数名注册安全的 Sprig 函数。同一
 | `$labels` | `map[string]string` | 告警标签，与 `.DataLabels` 相同。 |
 | `$values` | `map[string]float64` | 告警计算中使用到的数值，与 `.Values` 相同。 |
 | `$value` | `float64` | 主告警值，与 `.Value` 相同。 |
-| `$appendLabels` | `map[string]string` | 规则上配置的附加标签。 |
+| `$appendLabels` | `map[string]string` | 规则上配置的附加标签。使用 Go 模板的附加标签在这里是模板原文，推送前才会渲染，见[附加标签的写法](/zh/monitors/quickstart/quickstart#append-label-syntax)。 |
 | `$annotations` | `map[string]string` | 规则自定义字段和查询结果携带的附加信息。 |
 | `$dsType` | `string` | 数据源类型。 |
 | `$dsName` | `string` | 数据源名称。 |

zh/monitors/alert-rules/query-result-fields.mdx

@@ -142,6 +142,37 @@ Critical: $A.error_count > 20 and $B.latency_ms > 1000
 数据缺失告警会携带该告警对象最后一次成功查询时的附加信息。如果查询从未返回过数据，则没有可携带的查询附加信息。
 </Note>
 
+<span id="query-fields-as-labels"></span>
+## 把附加信息作为告警标签推送
+
+附加信息推送到 On-call 时带有 `__alert_rule_annotation_` 前缀，协作空间的通知模板、分派策略和[告警处理](/zh/on-call/integration/alert-integration/alert-pipelines)按普通标签名（例如 `labels.msg`）匹配时读不到它们。需要时，可以在规则的[附加标签](/zh/monitors/quickstart/quickstart#append-label-syntax)中用 Go 模板把附加信息转成普通标签。
+
+例如按服务聚合错误日志，同时在通知中保留最新一条日志：
+
+```sql
+SELECT service, namespace, COUNT(*) AS value,
+       MAX(datetime) AS datetime,
+       MAX_BY(msg, datetime) AS msg,
+       MAX_BY(trace_id, datetime) AS tid
+FROM error_logs
+WHERE datetime >= NOW() - INTERVAL 1 MINUTE
+GROUP BY service, namespace
+```
+
+标签字段选择 `service`、`namespace`，`msg`、`tid`、`datetime` 自动成为附加信息。再配置附加标签：
+
+```text
+msg      = {{ index $annotations "$A.msg" }}
+tid      = {{ index $annotations "$A.tid" }}
+datetime = {{ index $annotations "$A.datetime" }}
+```
+
+这样每个服务只产生一个告警实例，推送给 On-call 的 `msg`、`tid`、`datetime` 是该服务最新一条日志的真实内容，现有通知模板和分派策略无需修改。
+
+<Note>
+查询附加信息需要 monit-edge `v0.53.0` 或以上版本。更早版本的告警引擎不提供这些附加信息，模板中读不到对应的值。
+</Note>
+
 ## 查询结果行数上限
 
 Edge 分别限制周期告警查询和交互预览查询。以下是默认值，部署者可以独立调整：

zh/monitors/quickstart/quickstart.mdx

@@ -77,7 +77,35 @@ keywords: ["入门指南", "monitedge", "数据源", "告警规则", "快速开
 |--------|------|
 | **所属分组** | 规则所在的分组路径（如“默认分组 / 数据库告警”）。如果分组已被删除或您无权访问，需要返回规则列表重新选择分组 |
 | **规则名称** | 告警规则的名称，不支持引用变量（固定名称便于过滤、聚合操作）。同一分组内必须唯一；导入、编辑或移动规则时如与目标分组中已有规则重名，操作会失败 |
-| **附加标签** | 类似 Prometheus 中的 `labels`，会附加到所有告警事件上，便于过滤、路由、抑制 |
+| **附加标签** | 类似 Prometheus 中的 `labels`，会附加到所有告警事件上，便于过滤、路由、抑制。值的写法见下文 |
+
+<span id="append-label-syntax"></span>
+#### 附加标签的写法
+
+附加标签的值有三种写法，按值的内容区分：
+
+| 写法 | 示例 | 处理方式 |
+|------|------|----------|
+| 普通文本或 `${标签名}` | `team=ops`、`instance=${host}` | 告警引擎用告警标签替换 `${标签名}` |
+| 包含 `{{` 的 Go 模板 | `msg={{ index $annotations "$A.msg" }}` | 推送到协作空间之前渲染，渲染结果作为普通标签推送 |
+| 以 `[TPL]` 开头 | `owner=[TPL]{{ .Labels.team }}` | 原样交给 On-call，由 On-call 渲染，写法见[告警处理](/zh/on-call/integration/alert-integration/alert-pipelines) |
+
+Go 模板可以使用以下变量：
+
+| 变量 | 说明 |
+|------|------|
+| `$labels` | 告警的数据标签，例如 `{{ $labels.service }}` |
+| `$annotations` | 查询结果附加信息和规则自定义字段。查询附加信息的 key 为 `$<查询名称>.<字段名称>`，需要用 `index` 读取，例如 `{{ index $annotations "$A.msg" }}`。详见[查询结果字段映射](/zh/monitors/alert-rules/query-result-fields#query-fields-as-labels) |
+| `$values` | 告警计算中使用到的数值，例如 `{{ index $values "$A.value" }}` |
+| `$severity` | 告警级别 |
+| `$status` | `firing` 或 `recovered` |
+
+- 模板只支持 `if` / `else` 和 `index`、`len`、`printf`、`print`、`replace`、`urlquery` 以及比较、逻辑函数，不支持 `range`、`with`、`define`。
+- 读取不存在的 key 时，`$labels` 和 `$annotations` 得到空字符串，`$values` 得到 `0`。渲染结果为空的标签不会推送。
+- 同一个值不能同时使用 `${...}` 和 `{{...}}`。
+- 渲染失败的标签不会推送，告警事件照常推送，错误原因写入 `__alert_rule_label_template_error` 标签，可在告警详情中查看。
+- 标签名首尾的空白会在保存时去掉，去掉后不能重复；标签名不能以 `__alert_rule_` 开头。全部附加标签按 JSON 计合计不超过 1024 个字符，`job` 和 `instance` 的值不超过 255 个字符。
+- 告警引擎渲染备注描述、自定义字段和标题时，`$appendLabels` 中的模板标签仍是模板原文。需要在这些位置使用查询结果时，请直接引用 `$annotations`。
 
 ### 数据源与查询