pingcap · ti-chi-bot · Jun 26, 2023 · Jun 15, 2023 · Jun 15, 2023 · Jun 15, 2023
diff --git a/error-codes.md b/error-codes.md
@@ -393,6 +393,14 @@ TiDB 兼容 MySQL 的错误码，在大多数情况下，返回和 MySQL 一样
 
     在尝试消耗超过资源组的限制时返回该错误。一般出现该错误，是由于单次事务太大或者并发太多导致，需调整事务大小或减少客户端并发数。
 
+* Error Number: 8253
+
+    查询终止，因为满足 Runaway Queries 的条件。请参考 [Runaway Queries](/tidb-resource-control.md#管理资源消耗超出预期的查询-runaway-queries)。
+
+* Error Number: 8254
+
+    查询终止，因为被 Runaway Queries 免疫命中。请参考 [Runaway Queries](/tidb-resource-control.md#管理资源消耗超出预期的查询-runaway-queries)。
+
 * Error Number: 9001
 
     完整的报错信息为 `ERROR 9001 (HY000) : PD Server Timeout`。

diff --git a/information-schema/information-schema-resource-groups.md b/information-schema/information-schema-resource-groups.md
@@ -64,11 +64,11 @@ SELECT * FROM information_schema.resource_groups WHERE NAME = 'rg1'; -- 查看
 ```
 
 ```sql
-+------+------------+----------+-----------+
-| NAME | RU_PER_SEC | PRIORITY | BURSTABLE |
-+------+------------+----------+-----------+
-| rg1  |       1000 | MEDIUM   | NO        |
-+------+------------+----------+-----------+
++------+------------+----------+-----------+-------------+
+| NAME | RU_PER_SEC | PRIORITY | BURSTABLE | QUERY_LIMIT |
++------+------------+----------+-----------+-------------+
+| rg1  | 1000       | MEDIUM   | NO        | NULL        |
++------+------------+----------+-----------+-------------+
 1 row in set (0.00 sec)
 ```
 

diff --git a/mysql-schema.md b/mysql-schema.md
@@ -56,9 +56,14 @@ aliases: ['/docs-cn/dev/system-tables/system-table-overview/','/docs-cn/dev/refe
 
 ## TTL 相关系统表
 
-* `mysql.tidb_ttl_table_status` 所有 TTL 表的上一次执行与正在执行的 TTL 任务
-* `mysql.tidb_ttl_task` 正在执行的 TTL 子任务
-* `mysql.tidb_ttl_job_history` 过去 90 天内 TTL 任务的执行历史
+* `tidb_ttl_table_status` 所有 TTL 表的上一次执行与正在执行的 TTL 任务
+* `tidb_ttl_task` 正在执行的 TTL 子任务
+* `tidb_ttl_job_history` 过去 90 天内 TTL 任务的执行历史
+
+## Runaway Queries 相关系统表
+
+* `tidb_runaway_queries` 过去一定时间内所有识别到的 Runaway Queries 的历史记录
+* `tidb_runaway_quarantined_watch` 现在有效的和已过期的 Runaway Queries 的免疫规则
 
 ## 其它系统表
 

diff --git a/sql-statements/sql-statement-alter-resource-group.md b/sql-statements/sql-statement-alter-resource-group.md
@@ -28,11 +28,34 @@ DirectResourceGroupOption ::=
     "RU_PER_SEC" EqOpt stringLit
 |   "PRIORITY" EqOpt ResourceGroupPriorityOption
 |   "BURSTABLE"
+|   "BURSTABLE" EqOpt Boolean
+|   "QUERY_LIMIT" EqOpt '(' ResourceGroupRunawayOptionList ')'
+|   "QUERY_LIMIT" EqOpt '(' ')'
+|   "QUERY_LIMIT" EqOpt "NULL"
 
 ResourceGroupPriorityOption ::=
-    LOW 
+    LOW
 |   MEDIUM
 |   HIGH
+
+ResourceGroupRunawayOptionList ::= 
+    DirectResourceGroupRunawayOption
+|   ResourceGroupRunawayOptionList DirectResourceGroupRunawayOption
+|   ResourceGroupRunawayOptionList ',' DirectResourceGroupRunawayOption
+
+DirectResourceGroupRunawayOption ::=
+    "EXEC_ELAPSED" EqOpt stringLit
+|   "ACTION" EqOpt ResourceGroupRunawayActionOption
+|   "WATCH" EqOpt ResourceGroupRunawayWatchOption "DURATION" EqOpt stringLit
+
+ResourceGroupRunawayWatchOption ::=
+    EXACT
+|   SIMILAR
+
+ResourceGroupRunawayActionOption ::=
+    DRYRUN
+|   COOLDOWN
+|   KILL
 ```
 
 TiDB 支持以下 `DirectResourceGroupOption`, 其中 [Request Unit (RU)](/tidb-resource-control.md#什么是-request-unit-ru) 是 TiDB 对 CPU、IO 等系统资源统一抽象的单位。
@@ -42,10 +65,12 @@ TiDB 支持以下 `DirectResourceGroupOption`, 其中 [Request Unit (RU)](/tidb-
 | `RU_PER_SEC`  | 每秒 RU 填充的速度 | `RU_PER_SEC = 500` 表示此资源组每秒回填 500 个 RU。 |
 | `PRIORITY`    | 任务在 TiKV 上处理的绝对优先级  | `PRIORITY = HIGH` 表示优先级高。若未指定则默认为 `MEDIUM`。 |
 | `BURSTABLE`   | 允许对应的资源组超出配额后使用空余的系统资源。 |
+| `QUERY_LIMIT` | 当查询执行满足该条件时，识别该查询为 Runaway Query 并执行相应的操作 | `QUERY_LIMIT=(EXEC_ELAPSED='60s', ACTION=KILL, WATCH=EXACT DURATION='10m')` 表示当执行时间超过 60 秒后识别为 Runaway Query，对该查询执行终止操作，并在 10 分钟内对同样的 SQL 直接执行终止操作。`QUERY_LIMIT=()` 或 `QUERY_LIMIT=NULL` 则表示不进行 Runaway 控制。具体参数介绍参见[管理资源消耗超出预期的查询 (Runaway Queries)](/tidb-resource-control.md#管理资源消耗超出预期的查询-runaway-queries)。 ｜
 
 > **注意：**
 > 
 > `ALTER RESOURCE GROUP` 语句只能在全局变量 [`tidb_enable_resource_control`](/system-variables.md#tidb_enable_resource_control-从-v660-版本开始引入) 参数设置为 `ON` 时才能执行。
+> `ALTER RESOURCE GROUP` 语句支持以增量方式修改，未指定的参数保持不变。但其中 `QUERY_LIMIT` 作为一个整体，无法部分修改其中的参数。
 
 ## 示例
 
@@ -74,18 +99,19 @@ SELECT * FROM information_schema.resource_groups WHERE NAME ='rg1';
 ```
 
 ```sql
-+------+------------+----------+-----------+
-| NAME | RU_PER_SEC | PRIORITY | BURSTABLE |
-+------+------------+----------+-----------+
-| rg1  |       100  | MEDIUM   | YES       |
-+------+------------+----------+-----------+
++------+------------+----------+-----------+-------------+
+| NAME | RU_PER_SEC | PRIORITY | BURSTABLE | QUERY_LIMIT |
++------+------------+----------+-----------+-------------+
+| rg1  | 100        | MEDIUM   | YES       | NULL        |
++------+------------+----------+-----------+-------------+
 1 rows in set (1.30 sec)
 ```
 
 ```sql
 ALTER RESOURCE GROUP rg1
   RU_PER_SEC = 200
-  PRIORITY = LOW;
+  PRIORITY = LOW
+  QUERY_LIMIT = (EXEC_ELAPSED='1s' ACTION=COOLDOWN WATCH=EXACT[30s]);
 ```
 
 ```sql
@@ -97,11 +123,11 @@ SELECT * FROM information_schema.resource_groups WHERE NAME ='rg1';
 ```
 
 ```sql
-+------+------------+----------+-----------+
-| NAME | RU_PER_SEC | PRIORITY | BURSTABLE |
-+------+------------+----------+-----------+
-| rg1  |       200  | LOW      | NO        |
-+------+------------+----------+-----------+
++------+------------+----------+-----------+----------------------------------------------------+
+| NAME | RU_PER_SEC | PRIORITY | BURSTABLE | QUERY_LIMIT                                        |
++------+------------+----------+-----------+----------------------------------------------------+
+| rg1  | 200        | LOW      | YES       | EXEC_ELAPSED=1s, ACTION=COOLDOWN, WATCH=EXACT[30s] |
++------+------------+----------+-----------+----------------------------------------------------+
 1 rows in set (1.30 sec)
 ```
 

diff --git a/sql-statements/sql-statement-create-resource-group.md b/sql-statements/sql-statement-create-resource-group.md
@@ -28,11 +28,34 @@ DirectResourceGroupOption ::=
     "RU_PER_SEC" EqOpt stringLit
 |   "PRIORITY" EqOpt ResourceGroupPriorityOption
 |   "BURSTABLE"
+|   "BURSTABLE" EqOpt Boolean
+|   "QUERY_LIMIT" EqOpt '(' ResourceGroupRunawayOptionList ')'
+|   "QUERY_LIMIT" EqOpt '(' ')'
+|   "QUERY_LIMIT" EqOpt "NULL"
 
 ResourceGroupPriorityOption ::=
     LOW
 |   MEDIUM
 |   HIGH
+
+ResourceGroupRunawayOptionList ::= 
+    DirectResourceGroupRunawayOption
+|   ResourceGroupRunawayOptionList DirectResourceGroupRunawayOption
+|   ResourceGroupRunawayOptionList ',' DirectResourceGroupRunawayOption
+
+DirectResourceGroupRunawayOption ::=
+    "EXEC_ELAPSED" EqOpt stringLit
+|   "ACTION" EqOpt ResourceGroupRunawayActionOption
+|   "WATCH" EqOpt ResourceGroupRunawayWatchOption "DURATION" EqOpt stringLit
+
+ResourceGroupRunawayWatchOption ::=
+    EXACT
+|   SIMILAR
+
+ResourceGroupRunawayActionOption ::=
+    DRYRUN
+|   COOLDOWN
+|   KILL
 ```
 
 资源组的 `ResourceGroupName` 是全局唯一的，不允许重复。
@@ -43,7 +66,8 @@ TiDB 支持以下 `DirectResourceGroupOption`, 其中 [Request Unit (RU)](/tidb-
 |---------------|--------------|--------------------------------------|
 | `RU_PER_SEC`  | 每秒 RU 填充的速度 | `RU_PER_SEC = 500` 表示此资源组每秒回填 500 个 RU。 |
 | `PRIORITY`    | 任务在 TiKV 上处理的绝对优先级  | `PRIORITY = HIGH` 表示优先级高。若未指定，则默认为 `MEDIUM`。 |
-| `BURSTABLE`   | 允许对应的资源组超出配额后使用空余的系统资源。 |
+| `BURSTABLE`   | 允许对应的资源组超出配额后使用空余的系统资源。 | 
+| `QUERY_LIMIT` | 当查询执行满足该条件时，识别该查询为 Runaway Query 并进行相应的控制 | `QUERY_LIMIT=(EXEC_ELAPSED='60s', ACTION=KILL, WATCH=EXACT DURATION='10m')` 表示当执行时间超过 60 秒后识别为 Runaway Query，对该查询执行终止操作，并在 10 分钟内对同样的 SQL 直接执行终止操作。`QUERY_LIMIT=()` 或 `QUERY_LIMIT=NULL` 则表示不进行 Runaway 控制。具体参数介绍详见[管理资源消耗超出预期的查询 (Runaway Queries)](/tidb-resource-control.md#管理资源消耗超出预期的查询-runaway-queries)。 ｜
 
 > **注意：**
 >
@@ -75,7 +99,7 @@ Query OK, 0 rows affected (0.08 sec)
 
 ```sql
 CREATE RESOURCE GROUP IF NOT EXISTS rg2
-  RU_PER_SEC = 200;
+  RU_PER_SEC = 200 QUERY_LIMIT=(EXEC_ELAPSED='100ms', ACTION=KILL);
 ```
 
 ```sql
@@ -87,12 +111,12 @@ SELECT * FROM information_schema.resource_groups WHERE NAME ='rg1' or NAME = 'rg
 ```
 
 ```sql
-+------+------------+----------+-----------+
-| NAME | RU_PER_SEC | PRIORITY | BURSTABLE |
-+------+------------+----------+-----------+
-| rg1  |        100 | HIGH     | YES       |
-| rg2  |        200 | MEDIUM   | NO        |
-+------+------------+----------+-----------+
++------+------------+----------+-----------+---------------------------------+
+| NAME | RU_PER_SEC | PRIORITY | BURSTABLE | QUERY_LIMIT                     |
++------+------------+----------+-----------+---------------------------------+
+| rg1  | 100        | HIGH     | YES       | NULL                            |
+| rg2  | 200        | MEDIUM   | NO        | EXEC_ELAPSED=100ms, ACTION=KILL |
++------+------------+----------+-----------+---------------------------------+
 2 rows in set (1.30 sec)
 ```
 

diff --git a/sql-statements/sql-statement-drop-resource-group.md b/sql-statements/sql-statement-drop-resource-group.md
@@ -50,11 +50,11 @@ SELECT * FROM information_schema.resource_groups WHERE NAME ='rg1';
 ```
 
 ```sql
-+------+------------+----------+-----------+
-| NAME | RU_PER_SEC | PRIORITY | BURSTABLE |
-+------+------------+----------+-----------+
-| rg1  |       500  | MEDIUM   | YES       |
-+------+------------+----------+-----------+
++------+------------+----------+-----------+-------------+
+| NAME | RU_PER_SEC | PRIORITY | BURSTABLE | QUERY_LIMIT |
++------+------------+----------+-----------+-------------+
+| rg1  | 500        | MEDIUM   | YES       | NULL        |
++------+------------+----------+-----------+-------------+
 1 row in set (0.01 sec)
 ```
 
@@ -82,4 +82,4 @@ MySQL 也支持 [DROP RESOURCE GROUP](https://dev.mysql.com/doc/refman/8.0/en/dr
 
 * [ALTER RESOURCE GROUP](/sql-statements/sql-statement-alter-resource-group.md)
 * [CREATE RESOURCE GROUP](/sql-statements/sql-statement-create-resource-group.md)
-* [RU](/tidb-resource-control.md#什么是-request-unit-ru)
+* [RU](/tidb-resource-control.md#什么是-request-unit-ru)
diff --git a/tidb-resource-control.md b/tidb-resource-control.md
@@ -160,6 +160,113 @@ SET RESOURCE GROUP rg1;
 SELECT /*+ RESOURCE_GROUP(rg1) */ * FROM t limit 10;
 ```
 
+### 管理资源消耗超出预期的查询 (Runaway Queries)
+
+> **警告：**
+>
+> 该功能目前为实验特性，不建议在生产环境中使用。该功能可能会在未事先通知的情况下发生变化或删除。如果发现 bug，请在 GitHub 上提 [issue](https://github.com/pingcap/tidb/issues) 反馈。
+
+Runaway Queries 指那些执行时间或者消耗的资源超出预期的查询。自 v7.2.0 起，TiDB 资源管控引入了对 Runaway Queries 的管理。你可以针对某个资源组设置条件来识别 Runaway Queries，并自动发起应对操作，防止集群资源完全被 Runaway Queries 占用而影响其他正常查询。
+
+你可以通过在 [`CREATE RESOURCE GROUP`](/sql-statements/sql-statement-create-resource-group.md) 或者 [`ALTER RESOURCE GROUP`](/sql-statements/sql-statement-alter-resource-group.md) 中配置 `QUERY_LIMIT` 字段，管理资源组的 Runaway Queries。
+
+#### `QUERY_LIMIT` 参数说明
+
+支持的条件设置：
+
+- `EXEC_ELAPSED`: 当查询执行的时间超限时，识别为 Runaway Query。
+
+支持的应对操作 (`ACTION`)：
+
+- `DRYRUN`：对执行 Query 不做任何操作，仅记录识别的 Runaway Query。主要用于观测设置条件是否合理。
+- `COOLDOWN`：将查询的执行优先级降到最低，查询仍旧会以低优先级继续执行，不占用其他操作的资源。
+- `KILL`：识别到的查询将被自动终止，报错 `Query execution was interrupted, identified as runaway query`。
+
+为了避免并发的 Runaway Queries 太多，在被条件识别前就将系统资源耗尽，资源管控引入了一个快速识别的免疫机制。借助子句 `WATCH`，当某一个查询被识别为 Runaway Query 之后，在接下来的一段时间里（通过 `DURATION` 定义） ，当前 TiDB 实例会将匹配到的查询直接标记为 Runaway Query，而不再等待其被条件识别，并按照当前应对操作执行。其中 `KILL` 操作报错 `Quarantined and interrupted because of being in runaway watch list`。
+
+`WATCH` 有两种匹配方式：
+
+- `EXACT` 表示完全相同的 SQL 才会被快速识别
+- `SIMILAR` 表示会忽略字面值 (Literal)，通过 Plan Digest 匹配所有模式 (Pattern) 相同的 SQL
+
+`QUERY_LIMIT` 具体格式如下：
+
+| 参数            | 含义           | 备注                                   |
+|---------------|--------------|--------------------------------------|
+| `EXEC_ELAPSED`  | 当查询执行时间超过该值后被识别为 Runaway Query | EXEC_ELAPSED =`60s` 表示查询的执行时间超过 60 秒则被认为是 Runaway Query。 |
+| `ACTION`    | 当识别到 Runaway Query 时进行的动作 | 可选值有 `DRYRUN`，`COOLDOWN`，`KILL`。 |
+| `WATCH`   | 快速匹配已经识别到的 Runaway Query，即在一定时间内再碰到相同或相似查询直接进行相应动作 | 可选项，配置例如 `WATCH=SIMILAR DURATION '60s'`、`WATCH=EXACT DURATION '1m'`。 |
+
+#### 示例
+
+1. 创建 `rg1` 资源组，限额是每秒 500 RU，并且定义超过 60 秒为 Runaway Query，并对 Runaway Query 降低优先级执行。
+
+    ```sql
+    CREATE RESOURCE GROUP IF NOT EXISTS rg1 RU_PER_SEC = 500 QUERY_LIMIT=(EXEC_ELAPSED='60s', ACTION=COOLDOWN);
+    ```
+
+2. 修改 `rg1` 资源组, 对 Runaway Query 直接终止，并且在接下来的 10 分钟里，把相同模式的查询直接标记为 Runaway Query。
+
+    ```sql
+    ALTER RESOURCE GROUP rg1 QUERY_LIMIT=(EXEC_ELAPSED='60s', ACTION=KILL, WATCH=SIMILAR DURATION='10m');
+    ```
+
+3. 修改 `rg1` 资源组，取消 Runaway Queries 检查。
+
+    ```sql
+    ALTER RESOURCE GROUP rg1 QUERY_LIMIT=NULL;
+    ```
+
+#### 可观测性
+
+可以通过以下系统表获得 Runaway 相关的更多信息：
+
++ `mysql.tidb_runaway_queries` 表中包含了过去一定时间内所有识别到的 Runaway Queries 的历史记录。以其中一行为例：
+
+    ```sql
+    MySQL [(none)]> SELECT * FROM mysql.tidb_runaway_queries LIMIT 1\G;
+    *************************** 1. row ***************************
+    resource_group_name: rg1
+                   time: 2023-06-16 17:40:22
+             match_type: identify
+                 action: kill
+           original_sql: select * from sbtest.sbtest1
+            plan_digest: 5b7d445c5756a16f910192ad449c02348656a5e9d2aa61615e6049afbc4a82e
+            tidb_server: 127.0.0.1:4000
+    ```
+
+    其中，`match_type` 为该 Runaway Query 的来源，其值如下：
+
+    - `identify` 表示命中条件。
+    - `watch` 表示被免疫命中。
+
++ `mysql.tidb_runaway_quarantined_watch` 表中包含了 Runaway Queries 的免疫规则记录。以其中两行为例：
+
+    ```sql
+    MySQL [(none)]> SELECT * FROM mysql.tidb_runaway_quarantined_watch LIMIT 2\G;
+    *************************** 1. row ***************************
+    resource_group_name: rg1
+             start_time: 2023-06-16 17:40:22
+               end_time: 2023-06-16 18:10:22
+                  watch: similar
+             watch_text: 5b7d445c5756a16f910192ad449c02348656a5e9d2aa61615e6049afbc4a82e
+            tidb_server: 127.0.0.1:4000
+    *************************** 2. row ***************************
+    resource_group_name: rg1
+             start_time: 2023-06-16 17:42:35
+               end_time: 2023-06-16 18:12:35
+                  watch: exact
+             watch_text: select * from sbtest.sbtest1
+            tidb_server: 127.0.0.1:4000
+    ```
+
+    其中：
+
+    - `start_time` 和 `end_time` 表示该免疫有效的时间范围。
+    - `watch` 表示被免疫命中，其值如下：
+        - `similar` 表示按照 Plan Digest 匹配，此时列 `watch_text` 显示的是 Plan Digest。
+        - `exact` 表示按照 SQL 文本匹配，此时列 `watch_text` 显示的是 SQL 文本。
+
 ## 关闭资源管控特性
 
 1. 执行以下命令关闭资源管控特性：
@@ -184,7 +291,7 @@ TiDB Dashboard 中可以查看当前 [`RESOURCE_GROUPS`](/information-schema/inf
 
 ## 常见问题
 
-1. 如果我暂时不想使用资源组对资源进行管控，是否一定要关闭这个特性？ 
+1. 如果我暂时不想使用资源组对资源进行管控，是否一定要关闭这个特性？
 
     不需要。没有指定任何资源组的用户，将被放入系统预定义的 `default` 资源组，而 `default` 资源组默认拥有无限用量。当所有用户都属于 `default` 资源组时，资源分配方式与关闭资源管控时相同。