docs(trigger): for and keep_firing_for (#2251)

fengys1996 · web-flow · commit 2cf31eb81fcc · 2025-12-11T14:28:38.000+08:00
diff --git a/docs/reference/sql/trigger-syntax.md b/docs/reference/sql/trigger-syntax.md
@@ -21,6 +21,8 @@ CREATE TRIGGER [IF NOT EXISTS] <trigger_name>
         ON (<query_expression>) EVERY <interval_expression>
         [LABELS (<label_name>=<label_val>, ...)]
         [ANNOTATIONS (<annotation_name>=<annotation_val>, ...)]
+        [FOR <interval_expression>]
+        [KEEP FIRING FOR <interval_expression>]
         NOTIFY (
                 WEBHOOK <notify_name1> URL '<url1>' [WITH (<parameter1>=<value1>, ...)],
                 WEBHOOK <notify_name2> URL '<url2>' [WITH (<parameter2>=<value2>, ...)]
@@ -34,12 +36,11 @@ CREATE TRIGGER [IF NOT EXISTS] <trigger_name>
 
 #### Query expression
 
-The SQL query which be executed periodically. The notification will be fired
-if query result is not empty. If query result has multiple rows, a notification
-will be fired for each row.
+The SQL query specified in the `ON` clause is executed periodically. Its evaluation
+result may produce one or more alert instances, depending on the returned rows.
 
-In addition, the Trigger will extract the `labels` and `annotations` from the
-query result, and attach them to the notification message along with the key-value
+The Trigger extracts `labels` and `annotations` from the query result and attaches
+them to each alert instance. These values are combined with the static key-value
 pairs specified in the `LABELS` and `ANNOTATIONS` clauses.
 
 The extraction rules are as follows:
@@ -48,6 +49,9 @@ The extraction rules are as follows:
     of labels is the column name or alias without the `label_` prefix.
 - Extract the other columns to `ANNOTATIONS`. The key of annotations is the
     column name.
+    
+It is worth noting that each alert instance is uniquely identified by its label
+set. Multiple rows with the same labels will only create a single alert instance.
 
 For example, the query expression is as follows:
 
@@ -64,9 +68,9 @@ Assume the query result is not empty and looks like this:
 | collector1       | host1      | 12  |
 | collector2       | host2      | 15  |
 
-This will generate two notifications.
+This will generate two alert instances.
 
-The first notification will have the following labels and annotations:
+The first alert instance will have the following labels and annotations:
 
 - Labels:
     - collector: collector1
@@ -76,7 +80,7 @@ The first notification will have the following labels and annotations:
     - val: 12
     - the annotations defined in the `ANNOTATIONS` clause
 
-The second notification will have the following labels and annotations:
+The second alert instance will have the following labels and annotations:
 
 - Labels:
     - collector: collector2
@@ -99,6 +103,40 @@ It indicates how often the query is executed. e.g., `'5 minute'::INTERVAL`,
 
 For more details about how to write INTERVAL time, see [interval-type](/reference/sql/data-types.md#interval-type).
 
+### FOR clause
+
+The `FOR` clause controls how long an alert must remain active before it fires.
+Its behavior is similar to the `for` option in Prometheus Alerting Rules.
+
+When an alert instance appears in the evaluation results for the first time, it
+enters the `Pending` state, during which no notification is sent. If the alert 
+instance remains active throughout every evaluation within the duration specified
+by `FOR`, its state transitions from `Pending` to `Firing`, and a notification
+is sent immediately.
+
+If the `FOR` clause is not specified, the alert will not enter the `Pending`
+state. Instead, an alert instance transitions to the `Firing` state immediately
+upon its first appearance in the evaluation results, and a notification is sent
+immediately.
+
+### KEEP FIRING FOR clause
+
+The `KEEP FIRING FOR` clause controls how long an alert instance should remain
+in the `Firing` state after it first enters that state. Its behavior is similar
+to the `keep_firing_for` option in Prometheus Alerting Rules.
+
+Once an alert instance enters the `Firing` state, it will remain firing for at
+least the duration specified by `KEEP FIRING FOR`, even if it no longer appears
+in subsequent evaluation results.
+
+After the `KEEP FIRING FOR` duration has passed, if the alert instance does not
+appear in the next evaluation, it will be marked as resolved and will no longer
+remain in the `Firing` state.
+
+If the `KEEP FIRING FOR` clause is not specified, an alert instance will be 
+marked as resolved in the first evaluation where it no longer appears in the
+query results after entering the `Firing` state.
+
 ### Labels and Annotations clauses
 
 The LABELS and ANNOTATIONS clauses allow you to attach static key-value pairs
@@ -189,4 +227,3 @@ DROP TRIGGER IF EXISTS load1_monitor;
 ## Example
 
 Please refer to the [Trigger](/enterprise/trigger.md) documentation in the enterprise user guide for examples.
-
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/trigger-syntax.md b/i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/trigger-syntax.md
@@ -20,6 +20,8 @@ CREATE TRIGGER [IF NOT EXISTS] <trigger_name>
         ON (<query_expression>) EVERY <interval_expression>
         [LABELS (<label_name>=<label_val>, ...)]
         [ANNOTATIONS (<annotation_name>=<annotation_val>, ...)]
+        [FOR <interval_expression>]
+        [KEEP FIRING FOR <interval_expression>]
         NOTIFY (
                 WEBHOOK <notify_name1> URL '<url1>' [WITH (<parameter1>=<value1>, ...)],
                 WEBHOOK <notify_name2> URL '<url2>' [WITH (<parameter2>=<value2>, ...)]
@@ -33,18 +35,21 @@ CREATE TRIGGER [IF NOT EXISTS] <trigger_name>
 
 #### Query expression
 
-指定的 SQL 查询会被定期执行。若查询结果非空，则触发通知；若查询结果包含多行，则
-每一行都会触发一条独立通知。
+指定的 SQL 查询会被定期执行。每次查询的结果可能形成一个或多个告警实例，具体取决
+于返回的行。
 
-此外，Trigger 会从查询结果中提取 labels 与 annotations，并与 `LABELS` 和 `ANNOTATIONS`
-子句中指定的键值对一起附加到通知消息中。
+Trigger 会从查询结果中提取 `labels` 和 `annotations`，并将这些信息附加到每个告警
+实例上。同时，它们也会与 `LABELS` 和 `ANNOTATIONS` 子句中指定的静态键值对合并。
 
 提取规则如下：
 
 - 若列名（或别名）以 `label_` 开头，则将该列提取到 LABELS 中，键名为去掉 `label_`
     前缀后的列名（或别名）。
 - 其余所有列均提取到 ANNOTATIONS 中，键名即为列名（或别名）。
 
+值得注意的是，每个告警实例都由其 Label 集合唯一标识。如果多行查询结果生成的 Label
+集合相同，它们只会形成同一个告警实例。
+
 例如，查询表达式如下：
 
 ```sql
@@ -88,7 +93,35 @@ SELECT collect as label_collector, host as label_host, val
 - INTERVAL 表达式中**禁止**使用 `years` 和 `months`。月和年的时长是可变的，取决于具体的月份或年份，因此不适合用来定义固定的间隔。
 - 最小间隔为 1 秒。任何小于 1 秒的间隔都会被自动向上取整为 1 秒。
 
-有关 INTERVA L表达式的更多语法细节，请参见 [interval-type](/reference/sql/data-types.md#interval-type)。
+有关 INTERVAL 表达式的更多语法细节，请参见 [interval-type](/reference/sql/data-types.md#interval-type)。
+
+### FOR 子句
+
+`FOR <interval_expression>` 子句用于控制某个告警在真正触发前需要保持活跃的持续时
+间，其作用与 Prometheus Alerting Rules 中的 `for` 选项类似。
+
+当评估结果中首次出现某个告警实例时，它首先会进入 `Pending` 状态，此时不会触发通
+知。若该告警实例在 `FOR` 指定的持续时间内的每次评估中均保持活跃（即始终出现在查
+询结果中），则状态将由 `Pending` 转为 `Firing`，并立即发送通知。
+
+若未指定 `FOR` 子句，则告警不会进入 `Pending` 状态，而是在评估结果中首次出现该告
+警实例时立即进入 `Firing` 状态，并马上触发通知。
+
+### KEEP FIRING FOR 子句
+
+`KEEP FIRING FOR <interval_expression>` 子句用于控制某个告警实例在首次进入 `Firing`
+状态后，至少需要保持多长时间处于 `Firing` 状态，其作用与 Prometheus Alerting Rules
+中的 `keep_firing_for` 选项类似。
+
+当某个告警实例满足条件并进入 `Firing` 状态后，即便后续评估中该告警实例不再出现在
+查询结果中，只要距离首次进入 `Firing` 状态尚未超过 `KEEP FIRING FOR` 指定的时长，
+该告警实例仍会保持 `Firing` 状态。
+
+一旦超过 `KEEP FIRING FOR` 指定的时长，在下一次评估中如果该告警实例仍未出现在查
+询结果中，则会被标记为已恢复，不再处于 Firing 状态。
+
+若未指定 `KEEP FIRING FOR` 子句，则告警实例在进入 `Firing` 状态后，只要在后续评
+估中不再出现在查询结果中，就会在该次评估中被标记为已恢复。
 
 ### Labels 和 Annotations 子句
 
diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-1.0/reference/sql/trigger-syntax.md b/i18n/zh/docusaurus-plugin-content-docs/version-1.0/reference/sql/trigger-syntax.md
@@ -20,6 +20,8 @@ CREATE TRIGGER [IF NOT EXISTS] <trigger_name>
         ON (<query_expression>) EVERY <interval_expression>
         [LABELS (<label_name>=<label_val>, ...)]
         [ANNOTATIONS (<annotation_name>=<annotation_val>, ...)]
+        [FOR <interval_expression>]
+        [KEEP FIRING FOR <interval_expression>]
         NOTIFY (
                 WEBHOOK <notify_name1> URL '<url1>' [WITH (<parameter1>=<value1>, ...)],
                 WEBHOOK <notify_name2> URL '<url2>' [WITH (<parameter2>=<value2>, ...)]
@@ -33,18 +35,21 @@ CREATE TRIGGER [IF NOT EXISTS] <trigger_name>
 
 #### Query expression
 
-指定的 SQL 查询会被定期执行。若查询结果非空，则触发通知；若查询结果包含多行，则
-每一行都会触发一条独立通知。
+指定的 SQL 查询会被定期执行。每次查询的结果可能形成一个或多个告警实例，具体取决
+于返回的行。
 
-此外，Trigger 会从查询结果中提取 labels 与 annotations，并与 `LABELS` 和 `ANNOTATIONS`
-子句中指定的键值对一起附加到通知消息中。
+Trigger 会从查询结果中提取 `labels` 和 `annotations`，并将这些信息附加到每个告警
+实例上。同时，它们也会与 `LABELS` 和 `ANNOTATIONS` 子句中指定的静态键值对合并。
 
 提取规则如下：
 
 - 若列名（或别名）以 `label_` 开头，则将该列提取到 LABELS 中，键名为去掉 `label_`
     前缀后的列名（或别名）。
 - 其余所有列均提取到 ANNOTATIONS 中，键名即为列名（或别名）。
 
+值得注意的是，每个告警实例都由其 Label 集合唯一标识。如果多行查询结果生成的 Label
+集合相同，它们只会形成同一个告警实例。
+
 例如，查询表达式如下：
 
 ```sql
@@ -88,7 +93,35 @@ SELECT collect as label_collector, host as label_host, val
 - INTERVAL 表达式中**禁止**使用 `years` 和 `months`。月和年的时长是可变的，取决于具体的月份或年份，因此不适合用来定义固定的间隔。
 - 最小间隔为 1 秒。任何小于 1 秒的间隔都会被自动向上取整为 1 秒。
 
-有关 INTERVA L表达式的更多语法细节，请参见 [interval-type](/reference/sql/data-types.md#interval-type)。
+有关 INTERVAL 表达式的更多语法细节，请参见 [interval-type](/reference/sql/data-types.md#interval-type)。
+
+### FOR 子句
+
+`FOR <interval_expression>` 子句用于控制某个告警在真正触发前需要保持活跃的持续时
+间，其作用与 Prometheus Alerting Rules 中的 `for` 选项类似。
+
+当评估结果中首次出现某个告警实例时，它首先会进入 `Pending` 状态，此时不会触发通
+知。若该告警实例在 `FOR` 指定的持续时间内的每次评估中均保持活跃（即始终出现在查
+询结果中），则状态将由 `Pending` 转为 `Firing`，并立即发送通知。
+
+若未指定 `FOR` 子句，则告警不会进入 `Pending` 状态，而是在评估结果中首次出现该告
+警实例时立即进入 `Firing` 状态，并马上触发通知。
+
+### KEEP FIRING FOR 子句
+
+`KEEP FIRING FOR <interval_expression>` 子句用于控制某个告警实例在首次进入 `Firing`
+状态后，至少需要保持多长时间处于 `Firing` 状态，其作用与 Prometheus Alerting Rules
+中的 `keep_firing_for` 选项类似。
+
+当某个告警实例满足条件并进入 `Firing` 状态后，即便后续评估中该告警实例不再出现在
+查询结果中，只要距离首次进入 `Firing` 状态尚未超过 `KEEP FIRING FOR` 指定的时长，
+该告警实例仍会保持 `Firing` 状态。
+
+一旦超过 `KEEP FIRING FOR` 指定的时长，在下一次评估中如果该告警实例仍未出现在查
+询结果中，则会被标记为已恢复，不再处于 Firing 状态。
+
+若未指定 `KEEP FIRING FOR` 子句，则告警实例在进入 `Firing` 状态后，只要在后续评
+估中不再出现在查询结果中，就会在该次评估中被标记为已恢复。
 
 ### Labels 和 Annotations 子句
 
diff --git a/versioned_docs/version-1.0/reference/sql/trigger-syntax.md b/versioned_docs/version-1.0/reference/sql/trigger-syntax.md
@@ -21,6 +21,8 @@ CREATE TRIGGER [IF NOT EXISTS] <trigger_name>
         ON (<query_expression>) EVERY <interval_expression>
         [LABELS (<label_name>=<label_val>, ...)]
         [ANNOTATIONS (<annotation_name>=<annotation_val>, ...)]
+        [FOR <interval_expression>]
+        [KEEP FIRING FOR <interval_expression>]
         NOTIFY (
                 WEBHOOK <notify_name1> URL '<url1>' [WITH (<parameter1>=<value1>, ...)],
                 WEBHOOK <notify_name2> URL '<url2>' [WITH (<parameter2>=<value2>, ...)]
@@ -34,12 +36,11 @@ CREATE TRIGGER [IF NOT EXISTS] <trigger_name>
 
 #### Query expression
 
-The SQL query which be executed periodically. The notification will be fired
-if query result is not empty. If query result has multiple rows, a notification
-will be fired for each row.
+The SQL query specified in the `ON` clause is executed periodically. Its evaluation
+result may produce one or more alert instances, depending on the returned rows.
 
-In addition, the Trigger will extract the `labels` and `annotations` from the
-query result, and attach them to the notification message along with the key-value
+The Trigger extracts `labels` and `annotations` from the query result and attaches
+them to each alert instance. These values are combined with the static key-value
 pairs specified in the `LABELS` and `ANNOTATIONS` clauses.
 
 The extraction rules are as follows:
@@ -48,6 +49,9 @@ The extraction rules are as follows:
     of labels is the column name or alias without the `label_` prefix.
 - Extract the other columns to `ANNOTATIONS`. The key of annotations is the
     column name.
+    
+It is worth noting that each alert instance is uniquely identified by its label
+set. Multiple rows with the same labels will only create a single alert instance.
 
 For example, the query expression is as follows:
 
@@ -64,9 +68,9 @@ Assume the query result is not empty and looks like this:
 | collector1       | host1      | 12  |
 | collector2       | host2      | 15  |
 
-This will generate two notifications.
+This will generate two alert instances.
 
-The first notification will have the following labels and annotations:
+The first alert instance will have the following labels and annotations:
 
 - Labels:
     - collector: collector1
@@ -76,7 +80,7 @@ The first notification will have the following labels and annotations:
     - val: 12
     - the annotations defined in the `ANNOTATIONS` clause
 
-The second notification will have the following labels and annotations:
+The second alert instance will have the following labels and annotations:
 
 - Labels:
     - collector: collector2
@@ -99,6 +103,40 @@ It indicates how often the query is executed. e.g., `'5 minute'::INTERVAL`,
 
 For more details about how to write INTERVAL time, see [interval-type](/reference/sql/data-types.md#interval-type).
 
+### FOR clause
+
+The `FOR` clause controls how long an alert must remain active before it fires.
+Its behavior is similar to the `for` option in Prometheus Alerting Rules.
+
+When an alert instance appears in the evaluation results for the first time, it
+enters the `Pending` state, during which no notification is sent. If the alert 
+instance remains active throughout every evaluation within the duration specified
+by `FOR`, its state transitions from `Pending` to `Firing`, and a notification
+is sent immediately.
+
+If the `FOR` clause is not specified, the alert will not enter the `Pending`
+state. Instead, an alert instance transitions to the `Firing` state immediately
+upon its first appearance in the evaluation results, and a notification is sent
+immediately.
+
+### KEEP FIRING FOR clause
+
+The `KEEP FIRING FOR` clause controls how long an alert instance should remain
+in the `Firing` state after it first enters that state. Its behavior is similar
+to the `keep_firing_for` option in Prometheus Alerting Rules.
+
+Once an alert instance enters the `Firing` state, it will remain firing for at
+least the duration specified by `KEEP FIRING FOR`, even if it no longer appears
+in subsequent evaluation results.
+
+After the `KEEP FIRING FOR` duration has passed, if the alert instance does not
+appear in the next evaluation, it will be marked as resolved and will no longer
+remain in the `Firing` state.
+
+If the `KEEP FIRING FOR` clause is not specified, an alert instance will be 
+marked as resolved in the first evaluation where it no longer appears in the
+query results after entering the `Firing` state.
+
 ### Labels and Annotations clauses
 
 The LABELS and ANNOTATIONS clauses allow you to attach static key-value pairs
@@ -189,4 +227,3 @@ DROP TRIGGER IF EXISTS load1_monitor;
 ## Example
 
 Please refer to the [Trigger](/enterprise/trigger.md) documentation in the enterprise user guide for examples.
-
