Skip to content

*: add slow log control variables (tidb_slow_log_rules, tidb_slow_log_max_per_sec) and hint write_slow_log #21009

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
+68 −13
Open

*: add slow log control variables (tidb_slow_log_rules, tidb_slow_log_max_per_sec) and hint write_slow_log #21009

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9d5d049
*: add two variables tidb_slow_log_rules and tidb_slow_log_max_per_sec
zimulala Oct 17, 2025
a16078e
*: add WRITE_SLOW_LOG hint
zimulala Oct 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 46 additions & 13 deletions identify-slow-queries.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,25 +173,58 @@ Slow Query 基础信息：
- `Storage_from_kv`：从 v9.0.0 开始引入，表示该语句是否从 TiKV 读取数据。
- `Storage_from_mpp`：从 v9.0.0 开始引入，表示该语句是否从 TiFlash 读取数据。

## 相关系统变量
## 相关变量

### 相关 Hint

通过 Hit `WRITE_SLOW_LOG` 强制控制输出慢日志。
- 不受任何阈值或触发规则限制，即无论该 SQL 是否达到慢日志打印阈值，都会打印慢日志。
- 暂不支持强制关闭打印慢日志的方式（如 `WRITE_SLOW_LOG(FALSE)`）。

使用示例：
```sql
SELECT /*+ WRITE_SLOW_LOG */ count(*) FROM t t1, t t2 WHERE t1.a = t2.b;
```

### 相关系统变量

* [tidb_slow_log_threshold](/system-variables.md#tidb_slow_log_threshold)：设置慢日志的阈值，执行时间超过阈值的 SQL 语句将被记录到慢日志中。默认值是 300 ms。
* [tidb_slow_log_rules](/system-variables.md#tidb_slow_log_rules)：用于定义慢日志的触发规则，支持多维度指标组合条件，实现更加灵活和精细化的日志记录控制。此变量在新版本中引入，逐步替代传统的单一阈值控制方式，即替代 `tidb_slow_log_threshold` 的使用。
* 未设置 tidb_slow_log_rules
* 慢日志触发仍依赖 tidb_slow_log_threshold，Query_time 阈值取自该变量，以保持向后兼容。
* 已设置 tidb_slow_log_rules
* 配置的规则优先生效，tidb_slow_log_threshold 将被忽略。
* 若希望规则中仍包含 Query_time 的触发条件，可在设置规则时指定。
* 规则匹配逻辑（多条规则之间采用 OR 关系）：
* Session 作用域规则：优先匹配，如果匹配成功，则打印慢日志。
* Global 作用域规则：仅在 Session 规则未匹配时考虑：
* 若规则指定 ConnID 并与当前 Session 的 ConnID 匹配，则使用该规则。
* 若规则未指定 ConnID（全局通用规则），则使用该规则。
* 显示变量的行为与普通系统变量一致。
>
> 说明：`tidb_slow_log_rules` 用于替换单一阈值的方式，实现更灵活和精细化的慢日志控制，支持多维度指标组合条件。
>
> 建议：在启用 `tidb_slow_log_rules` 后，同时配置 `tidb_slow_log_max_per_sec`，以限制慢日志打印频率，防止基于规则的慢日志触发过于频繁。
* [tidb_slow_log_max_per_sec](/system-variables.md#tidb_slow_log_max_per_sec)：设置控制每秒打印慢日志的上限，默认值为 0。
* 当值为 0，其表示不限制每秒打印的慢日志数量。
* 当值大于 0 时，TiDB 每秒最多打印指定数量的慢日志，超过部分将被丢弃，不会写入慢日志文件。
* 建议在启用了 tidb_slow_log_rules 后配置该变量，以防规则触发频繁打印慢日志。
* [tidb_query_log_max_len](/system-variables.md#tidb_query_log_max_len)：设置慢日志记录 SQL 语句的最大长度。默认值是 4096 byte。
* [tidb_redact_log](/system-variables.md#tidb_redact_log)：设置慢日志记录 SQL 时是否将用户数据脱敏用 `?` 代替。默认值是 `0`，即关闭该功能。
* [tidb_enable_collect_execution_info](/system-variables.md#tidb_enable_collect_execution_info)：设置是否记录执行计划中各个算子的物理执行信息，默认值是 `1`。该功能对性能的影响约为 3%。开启该项后查看 `Plan` 的示例如下：

```sql
> select tidb_decode_plan('jAOIMAk1XzE3CTAJMQlmdW5jczpjb3VudChDb2x1bW4jNyktPkMJC/BMNQkxCXRpbWU6MTAuOTMxNTA1bXMsIGxvb3BzOjIJMzcyIEJ5dGVzCU4vQQoxCTMyXzE4CTAJMQlpbmRleDpTdHJlYW1BZ2dfOQkxCXQRSAwyNzY4LkgALCwgcnBjIG51bTogMQkMEXMQODg0MzUFK0hwcm9jIGtleXM6MjUwMDcJMjA2HXsIMgk1BWM2zwAAMRnIADcVyAAxHcEQNQlOL0EBBPBbCjMJMTNfMTYJMQkzMTI4MS44NTc4MTk5MDUyMTcJdGFibGU6dCwgaW5kZXg6aWR4KGEpLCByYW5nZTpbLWluZiw1MDAwMCksIGtlZXAgb3JkZXI6ZmFsc2UJMjUBrgnQVnsA');
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| tidb_decode_plan('jAOIMAk1XzE3CTAJMQlmdW5jczpjb3VudChDb2x1bW4jNyktPkMJC/BMNQkxCXRpbWU6MTAuOTMxNTA1bXMsIGxvb3BzOjIJMzcyIEJ5dGVzCU4vQQoxCTMyXzE4CTAJMQlpbmRleDpTdHJlYW1BZ2dfOQkxCXQRSAwyNzY4LkgALCwgcnBjIG51bTogMQkMEXMQODg0MzUFK0hwcm9jIGtleXM6MjUwMDcJMjA2HXsIMg |
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| id task estRows operator info actRows execution info memory disk |
| StreamAgg_17 root 1 funcs:count(Column#7)->Column#5 1 time:10.931505ms, loops:2 372 Bytes N/A |
| └─IndexReader_18 root 1 index:StreamAgg_9 1 time:10.927685ms, loops:2, rpc num: 1, rpc time:10.884355ms, proc keys:25007 206 Bytes N/A |
| └─StreamAgg_9 cop 1 funcs:count(1)->Column#7 1 time:11ms, loops:25 N/A N/A |
| └─IndexScan_16 cop 31281.857819905217 table:t, index:idx(a), range:[-inf,50000), keep order:false 25007 time:11ms, loops:25 N/A N/A |
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
```
```sql
> select tidb_decode_plan('jAOIMAk1XzE3CTAJMQlmdW5jczpjb3VudChDb2x1bW4jNyktPkMJC/BMNQkxCXRpbWU6MTAuOTMxNTA1bXMsIGxvb3BzOjIJMzcyIEJ5dGVzCU4vQQoxCTMyXzE4CTAJMQlpbmRleDpTdHJlYW1BZ2dfOQkxCXQRSAwyNzY4LkgALCwgcnBjIG51bTogMQkMEXMQODg0MzUFK0hwcm9jIGtleXM6MjUwMDcJMjA2HXsIMgk1BWM2zwAAMRnIADcVyAAxHcEQNQlOL0EBBPBbCjMJMTNfMTYJMQkzMTI4MS44NTc4MTk5MDUyMTcJdGFibGU6dCwgaW5kZXg6aWR4KGEpLCByYW5nZTpbLWluZiw1MDAwMCksIGtlZXAgb3JkZXI6ZmFsc2UJMjUBrgnQVnsA');
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| tidb_decode_plan('jAOIMAk1XzE3CTAJMQlmdW5jczpjb3VudChDb2x1bW4jNyktPkMJC/BMNQkxCXRpbWU6MTAuOTMxNTA1bXMsIGxvb3BzOjIJMzcyIEJ5dGVzCU4vQQoxCTMyXzE4CTAJMQlpbmRleDpTdHJlYW1BZ2dfOQkxCXQRSAwyNzY4LkgALCwgcnBjIG51bTogMQkMEXMQODg0MzUFK0hwcm9jIGtleXM6MjUwMDcJMjA2HXsIMg |
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| id task estRows operator info actRows execution info memory disk |
| StreamAgg_17 root 1 funcs:count(Column#7)->Column#5 1 time:10.931505ms, loops:2 372 Bytes N/A |
| └─IndexReader_18 root 1 index:StreamAgg_9 1 time:10.927685ms, loops:2, rpc num: 1, rpc time:10.884355ms, proc keys:25007 206 Bytes N/A |
| └─StreamAgg_9 cop 1 funcs:count(1)->Column#7 1 time:11ms, loops:25 N/A N/A |
| └─IndexScan_16 cop 31281.857819905217 table:t, index:idx(a), range:[-inf,50000), keep order:false 25007 time:11ms, loops:25 N/A N/A |
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
```

在性能测试中可以关闭自动收集算子的执行信息：

Expand Down
22 changes: 22 additions & 0 deletions system-variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5072,6 +5072,28 @@ Query OK, 0 rows affected, 1 warning (0.00 sec)
- 单位：毫秒
- 输出慢日志的耗时阈值，默认为 300 ms。如果查询耗时大于这个值，会视作一个慢查询，并记录到慢查询日志。注意，当日志的输出级别 [`log.level`](/tidb-configuration-file.md#level) 是 `"debug"` 时，所有查询都会记录到慢日志，不受该变量的限制。

### `tidb_slow_log_rules`

- 作用域：SESSION | GLOBAL
- 是否持久化到集群：是
- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否
- 默认值：""
- 类型：字符串
- 用于定义慢日志的触发规则，支持基于多维度指标的组合条件，实现更加灵活和精细化的日志记录控制。
> **注意:**
>
> 建议在启用 [`tidb_slow_log_rules`](#tidb_slow_log_rules) 后，同时配置 [`tidb_slow_log_max_per_sec`](#tidb_slow_log_max_per_sec) 以限制慢日志打印频率，防止基于规则的慢日志触发过于频繁。

### `tidb_slow_log_max_per_sec`

- 作用域：GLOBAL
- 是否持久化到集群：是
- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否
- 默认值：`0`
- 类型：整数型
- 范围：`[0, 1000000]`
- 控制每秒打印慢日志每秒的次数上限，默认值 0。当该变量值为 0 时，则表示不限制每秒打印的慢日志数量。当该变量值大于 0 时，TiDB 会限制每秒打印的慢日志数量不超过该值，超过部分的慢日志将被丢弃，不会写入慢日志文件。该变量常与 [`tidb_slow_log_rules`](#tidb_slow_log_rules) 结合使用，以防止在高负载情况下产生过多的慢日志。

### `tidb_slow_query_file`

- 作用域：SESSION
Expand Down