Merge pull request #1072 from flashcatcloud/docs/monitors-recovery-values

docs(monitors): recovery notification values and MySQL query variables

Author: UlricQin

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

@@ -111,6 +111,65 @@ Example:
 {{- end }}
 ```
 
+<span id="recovery-values"></span>
+## Show values at recovery time in recovery notifications
+
+When an alert recovers, the description and custom fields (including `title`) are rendered again, and `$status` is `recovered`. Which check the numbers in `$values` come from depends on the check mode and the **Recovery mode**.
+
+### Values for each recovery mode
+
+| Check mode | Recovery mode | `$values` in the recovery notification |
+| --- | --- | --- |
+| **Threshold evaluation** | Recovery when no thresholds are triggered | Values at recovery time |
+| **Threshold evaluation** | Recovery only when conditions are met | Values at recovery time, including queries referenced only by the recovery expression |
+| **Threshold evaluation** | Recovery when expression finds data | Main query values; see the note below |
+| **Data exists** | Recover if no data | Values from the most recent firing or repeat notification |
+| **Data exists** | Recover when results found | Main query values; see the note below |
+
+In the two modes that use a recovery query, main query values are the values at recovery time if the main query still returns the alerting object. Otherwise, they're the values from the most recent firing or repeat notification. The recovery query only decides whether the alert recovers, and its results aren't available to the template. To show other values in recovery notifications, use a [related query](#recovery-related-query).
+
+<Note>
+When there are multiple values, `$value` is 0. When a rule has multiple queries or a query returns multiple value fields, read values by key with `getvalue $values "<key>"`.
+</Note>
+
+### Threshold evaluation: reference query values directly
+
+With the first two recovery modes, branch on `$status` in the template and reference the same key. In this example, main query A returns CPU usage:
+
+```gotemplate
+{{- if eq $status "firing" }}
+CPU usage {{ getvalue $values "$A" "%.1f" }}% exceeds the threshold.
+{{- else }}
+Recovered. Current CPU usage {{ getvalue $values "$A" "%.1f" }}%.
+{{- end }}
+```
+
+<span id="recovery-related-query"></span>
+### Data exists: get values at recovery time with a related query
+
+With **Recover if no data**, the recovering check finds no data, so `$values` only has the values from the most recent notification. To show values at recovery time, use a related query: related queries run every time a notification is sent, including recovery notifications, regardless of the check mode and recovery mode. Query the values you want to show, then reference them in the template through `$relates`.
+
+Related query results from SQL data sources are returned as text, so read them with `$row.Field "<column name>"`.
+
+Related query example: the main query detects error logs by `service`, and related query R1 counts errors in the last 5 minutes.
+
+```sql
+SELECT count(*) AS cnt
+FROM app_logs
+WHERE level = 'ERROR'
+  AND service = '${service}'
+  AND ts > now() - INTERVAL 5 MINUTE
+```
+
+```gotemplate
+{{- if eq $status "firing" }}
+Service {{ index $labels "service" }} has error logs.
+{{- else }}
+Service {{ index $labels "service" }} recovered. Errors in the last 5 minutes:
+{{- range $row := $relates.R1 }} {{ $row.Field "cnt" }}{{ end }}
+{{- end }}
+```
+
 ## Go template built-in functions
 
 These functions are provided by Go `text/template`.

en/monitors/alert-rules/mysql.mdx

@@ -13,7 +13,7 @@ Monitors supports using standard SQL syntax to query MySQL and trigger alerts ba
 | **Field Processing** | All field names are automatically converted to lowercase; please use lowercase letters when configuring |
 | **Time Processing** | Recommended to use `now()`, `unix_timestamp()` and other functions for time filtering |
 
-Unlike the other SQL data sources, MySQL alert SQL must be fully determined when saved: the query, related queries, and recovery queries cannot use the `${label_name}` placeholder or a `{{ $labels.<label_name> }}` template, or the rule cannot be saved.
+Related queries and recovery queries support the `${label_name}` variable and the Go template `{{ $labels.<label_name> }}`, which require alert engine `v0.76.0` or later. After substituting variables, the alert engine checks that the SQL is a read-only query; if it isn't, that query run fails. The main query doesn't support variables.
 
 ## Threshold evaluation mode
 
@@ -45,7 +45,7 @@ Monitors distinguishes alert objects by their label fields and evaluates thresho
 
 ### Recovery logic
 
-See [Alert recovery](/en/monitors/quickstart/quickstart#alert-recovery) for the recovery options. A recovery query must also be fully determined and cannot use runtime variables.
+See [Alert recovery](/en/monitors/quickstart/quickstart#alert-recovery) for the recovery options. A recovery query is a separate SQL statement that supports the `${label_name}` variable and the Go template `{{ $labels.<label_name> }}` (requires alert engine `v0.76.0` or later).
 
 ## Data exists mode
 

en/monitors/faq/faq.mdx

@@ -56,4 +56,13 @@ If the preview fails, common causes are:
 <Accordion id="notes-format" title="What format does the alert rule notes description support?">
 The notes description supports Markdown format. You can use headings, lists, links, code blocks, and other Markdown syntax to organize content. It also supports variable references, which embed dynamic values such as alert event labels and query results into the notes. Responders can understand the alert context quickly.
 </Accordion>
+
+<Accordion id="recovery-values" title="How do I show values at recovery time in recovery notifications?">
+Recovery notifications render the description again. Use `{{ if eq $status "recovered" }}` in the template to tell recovery notifications apart.
+
+- **Threshold evaluation**: with **Recovery when no thresholds are triggered** or **Recovery only when conditions are met**, `$values` holds the values at recovery time.
+- **Data exists**: with **Recover if no data**, the query finds no data at recovery, so `$values` holds the values from the most recent notification. To show values at recovery time, use a related query.
+
+For syntax and examples, see [Show values at recovery time in recovery notifications](/en/monitors/alert-rules/description-template#recovery-values).
+</Accordion>
 </AccordionGroup>

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

@@ -110,6 +110,65 @@ Monitors 告警规则的 **备注描述（Description）** 用于定义告警和
 {{- end }}
 ```
 
+<span id="recovery-values"></span>
+## 在恢复通知中显示恢复时的数值
+
+告警恢复时，备注描述和自定义字段（含 `title`）会重新渲染一次，此时 `$status` 为 `recovered`。`$values` 中是哪一次检测的数值，取决于检测方式和**恢复方式**。
+
+### 各恢复方式下的数值
+
+| 检测方式 | 恢复方式 | 恢复通知中 `$values` 的数值 |
+| --- | --- | --- |
+| **阈值判定** | 未触发任一阈值就算恢复 | 恢复时的数值 |
+| **阈值判定** | 结果满足条件才算恢复 | 恢复时的数值，包括恢复表达式额外引用的查询 |
+| **阈值判定** | 表达式查到数据就算恢复 | 主查询数值，见下方说明 |
+| **数据存在** | 查询检测查不到数据即恢复 | 最近一次告警或重复通知时的数值 |
+| **数据存在** | 恢复检测查到数据才恢复 | 主查询数值，见下方说明 |
+
+使用恢复查询的两种方式中，如果恢复时主查询仍能查到该告警对象，主查询数值是恢复时的数值，否则是最近一次告警或重复通知时的数值。恢复查询只用于判断是否恢复，查询结果不提供给模板。需要在恢复通知中展示其他数值时，请使用[关联查询](#recovery-related-query)。
+
+<Note>
+存在多个数值时 `$value` 为 0。规则有多个查询或查询返回多个值字段时，请用 `getvalue $values "<key>"` 按 key 读取。
+</Note>
+
+### 阈值判定：直接引用查询值
+
+使用前两种恢复方式时，在模板中按 `$status` 分支，引用同一个 key 即可。下例中主查询 A 返回 CPU 使用率：
+
+```gotemplate
+{{- if eq $status "firing" }}
+CPU 使用率 {{ getvalue $values "$A" "%.1f" }}%，超过阈值。
+{{- else }}
+已恢复，当前 CPU 使用率 {{ getvalue $values "$A" "%.1f" }}%。
+{{- end }}
+```
+
+<span id="recovery-related-query"></span>
+### 数据存在：用关联查询获取恢复时的数值
+
+使用“查询检测查不到数据即恢复”时，恢复这一次检测没有查到数据，`$values` 只能提供最近一次通知时的数值。需要恢复时的数值，请使用关联查询：每次发送通知（包括恢复通知）时都会执行一次关联查询，与检测方式和恢复方式无关。在关联查询中查询需要展示的数值，然后在模板中通过 `$relates` 引用。
+
+SQL 类数据源的关联查询结果以文本形式返回，请用 `$row.Field "<列名>"` 读取。
+
+关联查询示例：主查询按 `service` 检测错误日志，关联查询 R1 统计最近 5 分钟的错误数。
+
+```sql
+SELECT count(*) AS cnt
+FROM app_logs
+WHERE level = 'ERROR'
+  AND service = '${service}'
+  AND ts > now() - INTERVAL 5 MINUTE
+```
+
+```gotemplate
+{{- 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` 提供。

zh/monitors/alert-rules/mysql.mdx

@@ -14,7 +14,7 @@ Monitors 支持使用标准 SQL 语法对 MySQL 进行查询，并根据查询
 | **字段处理** | 所有字段名自动转换为小写，配置时请使用小写字母 |
 | **时间处理** | 建议使用 `now()`、`unix_timestamp()` 等函数进行时间过滤 |
 
-与其他 SQL 数据源不同，MySQL 告警 SQL 在保存时必须完全确定：查询、关联查询和恢复查询中都不能使用 `${label_name}` 占位符或 `{{ $labels.<标签名> }}` 模板，否则无法保存。
+关联查询和恢复查询支持 `${label_name}` 变量和 Go 模板 `{{ $labels.<标签名> }}`，需告警引擎 `v0.76.0` 及以上。告警引擎会在变量替换后检查 SQL 是否为只读查询，不满足时本次查询失败。主查询不支持变量。
 
 ## 阈值判定模式
 
@@ -46,7 +46,7 @@ Monitors 按标签字段区分告警对象，并使用值字段进行阈值判
 
 ### 恢复逻辑
 
-恢复方式见[告警恢复](/zh/monitors/quickstart/quickstart#告警恢复)。恢复查询同样必须完全确定，不能使用运行时变量。
+恢复方式见[告警恢复](/zh/monitors/quickstart/quickstart#告警恢复)。恢复查询是独立 SQL，支持 `${label_name}` 变量，也支持 Go 模板 `{{ $labels.<标签名> }}`（需告警引擎 `v0.76.0` 及以上）。
 
 ## 数据存在模式
 

zh/monitors/faq/faq.mdx

@@ -57,4 +57,13 @@ keywords: ["常见问题", "FAQ", "调试日志", "故障排查", "monitedge"]
 <Accordion id="notes-format" title="告警规则的备注描述支持什么格式？">
 备注描述支持 Markdown 格式，您可以使用标题、列表、链接、代码块等 Markdown 语法来组织内容。同时支持引用变量，将告警事件的标签值、查询结果等动态信息嵌入到备注中，方便值班人员快速了解告警上下文。
 </Accordion>
+
+<Accordion id="recovery-values" title="恢复通知中如何显示恢复时的数值？">
+恢复通知会重新渲染备注描述，在模板中用 `{{ if eq $status "recovered" }}` 区分恢复通知即可。
+
+- **阈值判定**：恢复方式为“未触发任一阈值就算恢复”或“结果满足条件才算恢复”时，`$values` 就是恢复时的数值。
+- **数据存在**：恢复方式为“查询检测查不到数据即恢复”时，恢复时已查不到数据，`$values` 是最近一次通知时的数值。需要恢复时的数值，请使用关联查询。
+
+写法和示例见[在恢复通知中显示恢复时的数值](/zh/monitors/alert-rules/description-template#recovery-values)。
+</Accordion>
 </AccordionGroup>