From bce6614e46305741b8685ac89c3b49fac16d5486 Mon Sep 17 00:00:00 2001 From: Lynn Date: Fri, 17 Oct 2025 15:39:54 +0800 Subject: [PATCH 01/43] *: add two variables tidb_slow_log_rules and tidb_slow_log_max_per_sec --- identify-slow-queries.md | 21 ++++++++++++++++++++- system-variables.md | 22 ++++++++++++++++++++++ 2 files changed, 42 insertions(+), 1 deletion(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index 4eb582daf8eb..7671a2c6bf90 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -173,8 +173,27 @@ Slow Query 基础信息： - `Storage_from_mpp`：从 v8.5.5 开始引入，表示该语句是否从 TiFlash 读取数据。 ## 相关系统变量 - * [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` 的示例如下： diff --git a/system-variables.md b/system-variables.md index 59808bbbf816..e23d048082fb 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5073,6 +5073,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 From e925a27e8d0713de09e2469150b919e80cc273fc Mon Sep 17 00:00:00 2001 From: Lynn Date: Wed, 22 Oct 2025 17:28:29 +0800 Subject: [PATCH 02/43] *: add WRITE_SLOW_LOG hint --- identify-slow-queries.md | 40 +++++++++++++++++++++++++++------------- 1 file changed, 27 insertions(+), 13 deletions(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index 7671a2c6bf90..4a3c1bf88059 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -172,7 +172,21 @@ Slow Query 基础信息： - `Storage_from_kv`：从 v8.5.5 开始引入，表示该语句是否从 TiKV 读取数据。 - `Storage_from_mpp`：从 v8.5.5 开始引入，表示该语句是否从 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 @@ -198,18 +212,18 @@ Slow Query 基础信息： * [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 | + +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + ``` 在性能测试中可以关闭自动收集算子的执行信息： From 914dbc26e1ee9274daaf929200182daf3e66e56e Mon Sep 17 00:00:00 2001 From: Lynn Date: Wed, 19 Nov 2025 10:30:31 +0800 Subject: [PATCH 03/43] *: add test info and tiny update --- identify-slow-queries.md | 32 +++++++++++++++++--------------- system-variables.md | 1 + 2 files changed, 18 insertions(+), 15 deletions(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index 4a3c1bf88059..5520c2ac2c78 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -177,10 +177,12 @@ Slow Query 基础信息： ### 相关 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; ``` @@ -189,25 +191,25 @@ 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_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`，以限制慢日志打印频率，防止基于规则的慢日志触发过于频繁。 + > 建议：在资源充足的测试环境（1 TiDB：16C/48G，3 TiKV：16C/48G）中，多次 sysbench 测试结果表明：当多维慢日志规则生成的慢日志量处于半小时内数百万级时，对性能影响较小；但若日志量达到千万级，则会导致 TPS、延迟出现明显下降。在业务负载较高或 CPU/内存接近瓶颈时，应谨慎配置 `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 后配置该变量，以防规则触发频繁打印慢日志。 + * 当值为 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` 的示例如下： diff --git a/system-variables.md b/system-variables.md index e23d048082fb..572f33b99e69 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5081,6 +5081,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) - 默认值："" - 类型：字符串 - 用于定义慢日志的触发规则，支持基于多维度指标的组合条件，实现更加灵活和精细化的日志记录控制。 + > **注意:** > > 建议在启用 [`tidb_slow_log_rules`](#tidb_slow_log_rules) 后，同时配置 [`tidb_slow_log_max_per_sec`](#tidb_slow_log_max_per_sec) 以限制慢日志打印频率，防止基于规则的慢日志触发过于频繁。 From d6dcd318cd647260b8d74d37758dfe9937783934 Mon Sep 17 00:00:00 2001 From: Lynn Date: Thu, 20 Nov 2025 16:43:06 +0800 Subject: [PATCH 04/43] *: address a comment --- system-variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-variables.md b/system-variables.md index 572f33b99e69..692d568c2e38 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5094,7 +5094,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) - 默认值：`0` - 类型：整数型 - 范围：`[0, 1000000]` -- 控制每秒打印慢日志每秒的次数上限，默认值 0。当该变量值为 0 时，则表示不限制每秒打印的慢日志数量。当该变量值大于 0 时，TiDB 会限制每秒打印的慢日志数量不超过该值，超过部分的慢日志将被丢弃，不会写入慢日志文件。该变量常与 [`tidb_slow_log_rules`](#tidb_slow_log_rules) 结合使用，以防止在高负载情况下产生过多的慢日志。 +- 控制每个 TiDB 每秒打印慢日志的次数上限，默认值 0。当该变量值为 0 时，则表示不限制每个节点每秒打印的慢日志数量。当该变量值大于 0 时，会限制每个节点每秒打印的慢日志数量不超过该值，超过部分的慢日志将被丢弃，不会写入慢日志文件。该变量常与 [`tidb_slow_log_rules`](#tidb_slow_log_rules) 结合使用，以防止在高负载情况下产生过多的慢日志。 ### `tidb_slow_query_file` From 828b6669a1076360f1902041553769e2228f7a0b Mon Sep 17 00:00:00 2001 From: Lynn Date: Fri, 21 Nov 2025 09:56:15 +0800 Subject: [PATCH 05/43] *: add version --- identify-slow-queries.md | 2 +- system-variables.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index 5520c2ac2c78..fccd3503d58d 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -190,7 +190,7 @@ 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](/system-variables.md#tidb_slow_log_rules)：用于定义慢日志的触发规则，支持多维度指标组合条件，实现更加灵活和精细化的日志记录控制。此变量在 v9.0.0 版本中引入，逐步替代传统的单一阈值控制方式，即替代 `tidb_slow_log_threshold` 的使用。 * 未设置 tidb_slow_log_rules * 慢日志触发仍依赖 tidb_slow_log_threshold，Query_time 阈值取自该变量，以保持向后兼容。 * 已设置 tidb_slow_log_rules diff --git a/system-variables.md b/system-variables.md index 692d568c2e38..13ec73f9df5a 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5073,7 +5073,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) - 单位：毫秒 - 输出慢日志的耗时阈值，默认为 300 ms。如果查询耗时大于这个值，会视作一个慢查询，并记录到慢查询日志。注意，当日志的输出级别 [`log.level`](/tidb-configuration-file.md#level) 是 `"debug"` 时，所有查询都会记录到慢日志，不受该变量的限制。 -### `tidb_slow_log_rules` +### `tidb_slow_log_rules` 从 v9.0.0 版本开始引入 - 作用域：SESSION | GLOBAL - 是否持久化到集群：是 @@ -5086,7 +5086,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) > > 建议在启用 [`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` +### `tidb_slow_log_max_per_sec` 从 v9.0.0 版本开始引入 - 作用域：GLOBAL - 是否持久化到集群：是 From 199c952061de52d94deaa19ad629f084d770771a Mon Sep 17 00:00:00 2001 From: lilin90 Date: Thu, 4 Dec 2025 18:25:55 +0800 Subject: [PATCH 06/43] Update format --- identify-slow-queries.md | 49 ++++++++++++++++++++-------------------- 1 file changed, 25 insertions(+), 24 deletions(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index fccd3503d58d..43018b062ec4 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -189,11 +189,11 @@ 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)：用于定义慢日志的触发规则，支持多维度指标组合条件，实现更加灵活和精细化的日志记录控制。此变量在 v9.0.0 版本中引入，逐步替代传统的单一阈值控制方式，即替代 `tidb_slow_log_threshold` 的使用。 - * 未设置 tidb_slow_log_rules +* [`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)：用于定义慢查询日志的触发规则，支持多维度指标组合条件，实现更加灵活和精细化的日志记录控制。此变量在 v9.0.0 版本中引入，逐步替代传统的单一阈值控制方式，即替代 `tidb_slow_log_threshold` 的使用。 + * 未设置 `tidb_slow_log_rules`： * 慢日志触发仍依赖 tidb_slow_log_threshold，Query_time 阈值取自该变量，以保持向后兼容。 - * 已设置 tidb_slow_log_rules + * 已设置 `tidb_slow_log_rules`： * 配置的规则优先生效，tidb_slow_log_threshold 将被忽略。 * 若希望规则中仍包含 Query_time 的触发条件，可在设置规则时指定。 * 规则匹配逻辑（多条规则之间采用 OR 关系）： @@ -202,30 +202,31 @@ SELECT /*+ WRITE_SLOW_LOG */ count(*) FROM t t1, t t2 WHERE t1.a = t2.b; * 若规则指定 ConnID 并与当前 Session 的 ConnID 匹配，则使用该规则。 * 若规则未指定 ConnID（全局通用规则），则使用该规则。 * 显示变量的行为与普通系统变量一致。 + + > 说明：`tidb_slow_log_rules` 用于替换单一阈值的方式，实现更灵活和精细化的慢查询日志控制，支持多维度指标组合条件。 > - > 说明：`tidb_slow_log_rules` 用于替换单一阈值的方式，实现更灵活和精细化的慢日志控制，支持多维度指标组合条件。 - > - > 建议：在资源充足的测试环境（1 TiDB：16C/48G，3 TiKV：16C/48G）中，多次 sysbench 测试结果表明：当多维慢日志规则生成的慢日志量处于半小时内数百万级时，对性能影响较小；但若日志量达到千万级，则会导致 TPS、延迟出现明显下降。在业务负载较高或 CPU/内存接近瓶颈时，应谨慎配置 `tidb_slow_log_rules`，避免规则过宽导致日志洪泛。建议结合 `tidb_slow_log_max_per_sec` 限制日志打印速率，以降低对业务性能的影响。 + > 建议：在资源充足的测试环境（1 TiDB：16C/48G，3 TiKV：16C/48G）中，多次 sysbench 测试结果表明：当多维慢查询日志规则生成的慢查询日志量处于半小时内数百万级时，对性能影响较小；但若日志量达到千万级，则会导致 TPS、延迟出现明显下降。在业务负载较高或 CPU/内存接近瓶颈时，应谨慎配置 `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 每秒最多打印指定数量的慢日志，超过部分将被丢弃，不会写入慢日志文件。 + * 当值大于 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 | - +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - ``` +* [`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 | + +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + ``` 在性能测试中可以关闭自动收集算子的执行信息： From d6b2ee4e94046ab8fb8cd38affcb193fe71f3421 Mon Sep 17 00:00:00 2001 From: lilin90 Date: Thu, 4 Dec 2025 18:38:02 +0800 Subject: [PATCH 07/43] Refine wording and format --- identify-slow-queries.md | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index 43018b062ec4..ecae21cc2f22 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -189,26 +189,27 @@ 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)：用于定义慢查询日志的触发规则，支持多维度指标组合条件，实现更加灵活和精细化的日志记录控制。此变量在 v9.0.0 版本中引入，逐步替代传统的单一阈值控制方式，即替代 `tidb_slow_log_threshold` 的使用。 - * 未设置 `tidb_slow_log_rules`： - * 慢日志触发仍依赖 tidb_slow_log_threshold，Query_time 阈值取自该变量，以保持向后兼容。 - * 已设置 `tidb_slow_log_rules`： - * 配置的规则优先生效，tidb_slow_log_threshold 将被忽略。 - * 若希望规则中仍包含 Query_time 的触发条件，可在设置规则时指定。 +* [`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)：用于定义慢查询日志的触发规则，支持多维度指标组合条件，以实现更加灵活和精细化的日志记录控制。该变量在 v9.0.0 版本中引入，逐步替代传统的单一阈值控制方式，即替代 `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（全局通用规则），则使用该规则。 + * 若规则指定 `ConnID` 并与当前 Session 的 `ConnID` 匹配，则使用该规则。 + * 若规则未指定 `ConnID`（全局通用规则），则使用该规则。 * 显示变量的行为与普通系统变量一致。 - > 说明：`tidb_slow_log_rules` 用于替换单一阈值的方式，实现更灵活和精细化的慢查询日志控制，支持多维度指标组合条件。 + > **Tip** > - > 建议：在资源充足的测试环境（1 TiDB：16C/48G，3 TiKV：16C/48G）中，多次 sysbench 测试结果表明：当多维慢查询日志规则生成的慢查询日志量处于半小时内数百万级时，对性能影响较小；但若日志量达到千万级，则会导致 TPS、延迟出现明显下降。在业务负载较高或 CPU/内存接近瓶颈时，应谨慎配置 `tidb_slow_log_rules`，避免规则过宽导致日志洪泛。建议结合 `tidb_slow_log_max_per_sec` 限制日志打印速率，以降低对业务性能的影响。 + > - `tidb_slow_log_rules` 用于替换单一阈值的方式，实现更灵活和精细化的慢查询日志控制，支持多维度指标组合条件。 + > - 在资源充足的测试环境（1 TiDB：16C/48G，3 TiKV：16C/48G）中，多次 sysbench 测试结果表明：当多维慢查询日志规则生成的慢查询日志量处于半小时内数百万级时，对性能影响较小；但若日志量达到千万级，则会导致 TPS、延迟出现明显下降。在业务负载较高或 CPU/内存接近瓶颈时，应谨慎配置 `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，其表示不限制每秒打印的慢日志数量。 +* [`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。 From 13812cada42ffa2d8490621ce5c1f51cd395ce79 Mon Sep 17 00:00:00 2001 From: Lynn Date: Fri, 5 Dec 2025 12:12:55 +0800 Subject: [PATCH 08/43] *: address comments --- identify-slow-queries.md | 12 +++++++----- system-variables.md | 2 +- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index ecae21cc2f22..cadff2696c1f 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -174,12 +174,14 @@ Slow Query 基础信息： ## 相关变量 +本节介绍慢查询日志相关的 Hint 与系统变量。 + ### 相关 Hint -通过 Hit `WRITE_SLOW_LOG` 强制控制输出慢日志。 +你可以通过 Hint `WRITE_SLOW_LOG` 强制控制输出慢查询日志。 -- 不受任何阈值或触发规则限制，即无论该 SQL 是否达到慢日志打印阈值，都会打印慢日志。 -- 暂不支持强制关闭打印慢日志的方式（如 `WRITE_SLOW_LOG(FALSE)`）。 +- 该 Hint 不受任何阈值或触发规则限制，即无论该 SQL 查询是否达到慢查询日志打印阈值，都会打印慢查询日志。 +- 目前只支持强制开启打印慢查询日志，暂不支持通过 `WRITE_SLOW_LOG(FALSE)`）强制关闭打印慢查询日志。 使用示例： @@ -208,10 +210,10 @@ SELECT /*+ WRITE_SLOW_LOG */ count(*) FROM t t1, t t2 WHERE t1.a = t2.b; > - `tidb_slow_log_rules` 用于替换单一阈值的方式，实现更灵活和精细化的慢查询日志控制，支持多维度指标组合条件。 > - 在资源充足的测试环境（1 TiDB：16C/48G，3 TiKV：16C/48G）中，多次 sysbench 测试结果表明：当多维慢查询日志规则生成的慢查询日志量处于半小时内数百万级时，对性能影响较小；但若日志量达到千万级，则会导致 TPS、延迟出现明显下降。在业务负载较高或 CPU/内存接近瓶颈时，应谨慎配置 `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。 +* [`tidb_slow_log_max_per_sec`](/system-variables.md#tidb_slow_log_max_per_sec)：用于设置每秒打印慢日志的上限，默认值为 0。 * 当值为 0 时，表示不限制每秒打印的慢日志数量。 * 当值大于 0 时，TiDB 每秒最多打印指定数量的慢查询日志，超过部分将被丢弃，不会写入慢日志文件。 - * 建议在启用了 tidb_slow_log_rules 后配置该变量，以防规则触发频繁打印慢日志。 + * 建议在启用了 `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` 的示例如下： diff --git a/system-variables.md b/system-variables.md index 13ec73f9df5a..bac094855254 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5094,7 +5094,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) - 默认值：`0` - 类型：整数型 - 范围：`[0, 1000000]` -- 控制每个 TiDB 每秒打印慢日志的次数上限，默认值 0。当该变量值为 0 时，则表示不限制每个节点每秒打印的慢日志数量。当该变量值大于 0 时，会限制每个节点每秒打印的慢日志数量不超过该值，超过部分的慢日志将被丢弃，不会写入慢日志文件。该变量常与 [`tidb_slow_log_rules`](#tidb_slow_log_rules) 结合使用，以防止在高负载情况下产生过多的慢日志。 +- 控制每个 TiDB 每秒打印慢日志的次数上限，默认值 0。当该变量值为 0 时，表示不限制每个节点每秒打印的慢日志数量。当该变量值大于 0 时，会限制每个节点每秒打印的慢日志数量不超过该值，超过部分的慢日志将被丢弃，不会写入慢日志文件。该变量常与 [`tidb_slow_log_rules`](#tidb_slow_log_rules) 结合使用，以防止在高负载情况下产生过多的慢日志。 ### `tidb_slow_query_file` From 2b9625a945315758e627a63d82d1fdbf1ea20eee Mon Sep 17 00:00:00 2001 From: Lynn Date: Fri, 5 Dec 2025 13:12:24 +0800 Subject: [PATCH 09/43] *: tiny update --- identify-slow-queries.md | 4 ++-- system-variables.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index cadff2696c1f..46247b839745 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -192,7 +192,7 @@ 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)：用于定义慢查询日志的触发规则，支持多维度指标组合条件，以实现更加灵活和精细化的日志记录控制。该变量在 v9.0.0 版本中引入，逐步替代传统的单一阈值控制方式，即替代 `tidb_slow_log_threshold` 的使用。 +* [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-从-v900-版本开始引入)：用于定义慢查询日志的触发规则，支持多维度指标组合条件，以实现更加灵活和精细化的日志记录控制。该变量在 v9.0.0 版本中引入，逐步替代传统的单一阈值控制方式，即替代 `tidb_slow_log_threshold` 的使用。 * 如果未设置 `tidb_slow_log_rules`： * 慢日志触发仍依赖 `tidb_slow_log_threshold`，`query_time` 阈值取自该变量，以保持向后兼容。 * 如果已设置 `tidb_slow_log_rules`： @@ -210,7 +210,7 @@ SELECT /*+ WRITE_SLOW_LOG */ count(*) FROM t t1, t t2 WHERE t1.a = t2.b; > - `tidb_slow_log_rules` 用于替换单一阈值的方式，实现更灵活和精细化的慢查询日志控制，支持多维度指标组合条件。 > - 在资源充足的测试环境（1 TiDB：16C/48G，3 TiKV：16C/48G）中，多次 sysbench 测试结果表明：当多维慢查询日志规则生成的慢查询日志量处于半小时内数百万级时，对性能影响较小；但若日志量达到千万级，则会导致 TPS、延迟出现明显下降。在业务负载较高或 CPU/内存接近瓶颈时，应谨慎配置 `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。 +* [`tidb_slow_log_max_per_sec`](/system-variables.md#tidb_slow_log_max_per_sec-从-v900-版本开始引入)：用于设置每秒打印慢日志的上限，默认值为 0。 * 当值为 0 时，表示不限制每秒打印的慢日志数量。 * 当值大于 0 时，TiDB 每秒最多打印指定数量的慢查询日志，超过部分将被丢弃，不会写入慢日志文件。 * 建议在启用了 `tidb_slow_log_rules` 后配置该变量，以防规则触发频繁打印慢日志。 diff --git a/system-variables.md b/system-variables.md index bac094855254..cafd0dc4622b 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5084,7 +5084,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) > **注意:** > -> 建议在启用 [`tidb_slow_log_rules`](#tidb_slow_log_rules) 后，同时配置 [`tidb_slow_log_max_per_sec`](#tidb_slow_log_max_per_sec) 以限制慢日志打印频率，防止基于规则的慢日志触发过于频繁。 +> 建议在启用 [`tidb_slow_log_rules`](#tidb_slow_log_rules-从-v900-版本开始引入) 后，同时配置 [`tidb_slow_log_max_per_sec`](#tidb_slow_log_max_per_sec-从-v900-版本开始引入) 以限制慢日志打印频率，防止基于规则的慢日志触发过于频繁。 ### `tidb_slow_log_max_per_sec` 从 v9.0.0 版本开始引入 @@ -5094,7 +5094,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) - 默认值：`0` - 类型：整数型 - 范围：`[0, 1000000]` -- 控制每个 TiDB 每秒打印慢日志的次数上限，默认值 0。当该变量值为 0 时，表示不限制每个节点每秒打印的慢日志数量。当该变量值大于 0 时，会限制每个节点每秒打印的慢日志数量不超过该值，超过部分的慢日志将被丢弃，不会写入慢日志文件。该变量常与 [`tidb_slow_log_rules`](#tidb_slow_log_rules) 结合使用，以防止在高负载情况下产生过多的慢日志。 +- 控制每个 TiDB 每秒打印慢日志的次数上限，默认值 0。当该变量值为 0 时，表示不限制每个节点每秒打印的慢日志数量。当该变量值大于 0 时，会限制每个节点每秒打印的慢日志数量不超过该值，超过部分的慢日志将被丢弃，不会写入慢日志文件。该变量常与 [`tidb_slow_log_rules`](#tidb_slow_log_rules-从-v900-版本开始引入) 结合使用，以防止在高负载情况下产生过多的慢日志。 ### `tidb_slow_query_file` From 8e281d1a2f0a601e685122fdfffdeea11a643877 Mon Sep 17 00:00:00 2001 From: Lynn Date: Tue, 9 Dec 2025 19:41:18 +0800 Subject: [PATCH 10/43] Update identify-slow-queries.md Co-authored-by: Lilian Lee --- identify-slow-queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index 46247b839745..c66694a04659 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -181,7 +181,7 @@ Slow Query 基础信息： 你可以通过 Hint `WRITE_SLOW_LOG` 强制控制输出慢查询日志。 - 该 Hint 不受任何阈值或触发规则限制，即无论该 SQL 查询是否达到慢查询日志打印阈值，都会打印慢查询日志。 -- 目前只支持强制开启打印慢查询日志，暂不支持通过 `WRITE_SLOW_LOG(FALSE)`）强制关闭打印慢查询日志。 +- 目前只支持强制开启打印慢查询日志，暂不支持通过 `WRITE_SLOW_LOG(FALSE)` 强制关闭打印慢查询日志。 使用示例： From ed4bfc80ebe6a43443ee38e2295e417ae5546ca0 Mon Sep 17 00:00:00 2001 From: Lynn Date: Tue, 9 Dec 2025 19:41:35 +0800 Subject: [PATCH 11/43] Update identify-slow-queries.md Co-authored-by: Lilian Lee --- identify-slow-queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index c66694a04659..ebdc32be2682 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -201,7 +201,7 @@ SELECT /*+ WRITE_SLOW_LOG */ count(*) FROM t t1, t t2 WHERE t1.a = t2.b; * 规则匹配逻辑（多条规则之间采用 OR 关系）： * Session 作用域规则：优先匹配，如果匹配成功，则打印慢日志。 * Global 作用域规则：仅在 Session 规则未匹配时考虑： - * 若规则指定 `ConnID` 并与当前 Session 的 `ConnID` 匹配，则使用该规则。 + * 若规则指定了 `ConnID` 并与当前 Session 的 `ConnID` 匹配，则使用该规则。 * 若规则未指定 `ConnID`（全局通用规则），则使用该规则。 * 显示变量的行为与普通系统变量一致。 From 1e92bce07f99a191fef0e1011d812595c39df33e Mon Sep 17 00:00:00 2001 From: Lynn Date: Tue, 9 Dec 2025 19:41:53 +0800 Subject: [PATCH 12/43] Update identify-slow-queries.md Co-authored-by: Lilian Lee --- identify-slow-queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index ebdc32be2682..f1c7a90844bc 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -213,7 +213,7 @@ SELECT /*+ WRITE_SLOW_LOG */ count(*) FROM t t1, t t2 WHERE t1.a = t2.b; * [`tidb_slow_log_max_per_sec`](/system-variables.md#tidb_slow_log_max_per_sec-从-v900-版本开始引入)：用于设置每秒打印慢日志的上限，默认值为 0。 * 当值为 0 时，表示不限制每秒打印的慢日志数量。 * 当值大于 0 时，TiDB 每秒最多打印指定数量的慢查询日志，超过部分将被丢弃，不会写入慢日志文件。 - * 建议在启用了 `tidb_slow_log_rules` 后配置该变量，以防规则触发频繁打印慢日志。 + * 建议在启用了 `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` 的示例如下： From 37497091c95ea79545ad654b6708a205d2a8ce5d Mon Sep 17 00:00:00 2001 From: Lynn Date: Tue, 9 Dec 2025 19:42:08 +0800 Subject: [PATCH 13/43] Update identify-slow-queries.md Co-authored-by: Lilian Lee --- identify-slow-queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index f1c7a90844bc..e142d49db209 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -215,7 +215,7 @@ SELECT /*+ WRITE_SLOW_LOG */ count(*) FROM t t1, t t2 WHERE t1.a = t2.b; * 当值大于 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_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 From 4901437ceba687312022ab05e94920f83f1b9d68 Mon Sep 17 00:00:00 2001 From: Lynn Date: Tue, 9 Dec 2025 19:43:37 +0800 Subject: [PATCH 14/43] Update identify-slow-queries.md Co-authored-by: Lilian Lee --- identify-slow-queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index e142d49db209..0dd722bfa3f9 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -216,7 +216,7 @@ SELECT /*+ WRITE_SLOW_LOG */ count(*) FROM t t1, t t2 WHERE t1.a = t2.b; * 建议在启用了 `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` 的示例如下： +* [`tidb_enable_collect_execution_info`](/system-variables.md#tidb_enable_collect_execution_info)：设置是否记录执行计划中各个算子的物理执行信息，默认值是 `1`。开启该功能会导致性能降低约 3%。开启后查看 `Plan` 的示例如下： ```sql > select tidb_decode_plan('jAOIMAk1XzE3CTAJMQlmdW5jczpjb3VudChDb2x1bW4jNyktPkMJC/BMNQkxCXRpbWU6MTAuOTMxNTA1bXMsIGxvb3BzOjIJMzcyIEJ5dGVzCU4vQQoxCTMyXzE4CTAJMQlpbmRleDpTdHJlYW1BZ2dfOQkxCXQRSAwyNzY4LkgALCwgcnBjIG51bTogMQkMEXMQODg0MzUFK0hwcm9jIGtleXM6MjUwMDcJMjA2HXsIMgk1BWM2zwAAMRnIADcVyAAxHcEQNQlOL0EBBPBbCjMJMTNfMTYJMQkzMTI4MS44NTc4MTk5MDUyMTcJdGFibGU6dCwgaW5kZXg6aWR4KGEpLCByYW5nZTpbLWluZiw1MDAwMCksIGtlZXAgb3JkZXI6ZmFsc2UJMjUBrgnQVnsA'); From bd9b6b5b0f1df10548eec34f40e9f5c62d831234 Mon Sep 17 00:00:00 2001 From: Lynn Date: Tue, 9 Dec 2025 19:43:47 +0800 Subject: [PATCH 15/43] Update system-variables.md Co-authored-by: Lilian Lee --- system-variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-variables.md b/system-variables.md index cafd0dc4622b..3821bb0c29c1 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5082,7 +5082,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) - 类型：字符串 - 用于定义慢日志的触发规则，支持基于多维度指标的组合条件，实现更加灵活和精细化的日志记录控制。 -> **注意:** +> **注意** > > 建议在启用 [`tidb_slow_log_rules`](#tidb_slow_log_rules-从-v900-版本开始引入) 后，同时配置 [`tidb_slow_log_max_per_sec`](#tidb_slow_log_max_per_sec-从-v900-版本开始引入) 以限制慢日志打印频率，防止基于规则的慢日志触发过于频繁。 From a38a576f28187942eaf27af63ee1a0e196774470 Mon Sep 17 00:00:00 2001 From: Lynn Date: Tue, 9 Dec 2025 19:44:01 +0800 Subject: [PATCH 16/43] Update system-variables.md Co-authored-by: Lilian Lee --- system-variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-variables.md b/system-variables.md index 3821bb0c29c1..06f517a0ca54 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5084,7 +5084,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) > **注意** > -> 建议在启用 [`tidb_slow_log_rules`](#tidb_slow_log_rules-从-v900-版本开始引入) 后，同时配置 [`tidb_slow_log_max_per_sec`](#tidb_slow_log_max_per_sec-从-v900-版本开始引入) 以限制慢日志打印频率，防止基于规则的慢日志触发过于频繁。 +> 建议在启用 [`tidb_slow_log_rules`](#tidb_slow_log_rules-从-v900-版本开始引入) 后，同时配置 [`tidb_slow_log_max_per_sec`](#tidb_slow_log_max_per_sec-从-v900-版本开始引入)，以限制慢日志打印频率，防止基于规则的慢日志触发过于频繁。 ### `tidb_slow_log_max_per_sec` 从 v9.0.0 版本开始引入 From 106b08a0c0ee41148d0da326151ab9e7daabe76e Mon Sep 17 00:00:00 2001 From: Lynn Date: Tue, 9 Dec 2025 19:44:19 +0800 Subject: [PATCH 17/43] Update system-variables.md Co-authored-by: Lilian Lee --- system-variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-variables.md b/system-variables.md index 06f517a0ca54..0b587ac1c017 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5094,7 +5094,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) - 默认值：`0` - 类型：整数型 - 范围：`[0, 1000000]` -- 控制每个 TiDB 每秒打印慢日志的次数上限，默认值 0。当该变量值为 0 时，表示不限制每个节点每秒打印的慢日志数量。当该变量值大于 0 时，会限制每个节点每秒打印的慢日志数量不超过该值，超过部分的慢日志将被丢弃，不会写入慢日志文件。该变量常与 [`tidb_slow_log_rules`](#tidb_slow_log_rules-从-v900-版本开始引入) 结合使用，以防止在高负载情况下产生过多的慢日志。 +- 控制每个 TiDB 节点每秒打印慢日志的次数上限，默认值为 `0`。当该变量值为 `0` 时，表示不限制每个节点每秒打印的慢日志数量。当该变量值大于 `0` 时，会限制每个节点每秒打印的慢日志数量不超过该值，超过部分的慢日志将被丢弃，不会写入慢日志文件。该变量常与 [`tidb_slow_log_rules`](#tidb_slow_log_rules-从-v900-版本开始引入) 结合使用，以防止在高负载情况下产生过多的慢日志。 ### `tidb_slow_query_file` From 46e001404d6b58f67d1d204d1256f57c5e86a05a Mon Sep 17 00:00:00 2001 From: lilin90 Date: Wed, 10 Dec 2025 11:05:23 +0800 Subject: [PATCH 18/43] Update wording for consistency --- identify-slow-queries.md | 54 +++++++++++++++++++--------------------- 1 file changed, 25 insertions(+), 29 deletions(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index 0dd722bfa3f9..c38ec70c25a5 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -58,7 +58,7 @@ Slow Query 基础信息： * `Compile_time`：表示这个语句在查询优化阶段花费的时间。 * `Optimize_time`：表示这个语句在优化查询计划阶段花费的时间。 * `Wait_TS`：表示这个语句在等待获取事务 TS 阶段花费的时间。 -* `Query`：表示 SQL 语句。慢日志里面不会打印 `Query`，但映射到内存表后，对应的字段叫 `Query`。 +* `Query`：表示 SQL 语句。慢查询日志里面不会打印 `Query`，但映射到内存表后，对应的字段叫 `Query`。 * `Digest`：表示 SQL 语句的指纹。 * `Txn_start_ts`：表示事务的开始时间戳，也是事务的唯一 ID，可以用这个值在 TiDB 日志中查找事务相关的其他日志。 * `Is_internal`：表示是否为 TiDB 内部的 SQL 语句。`true` 表示 TiDB 系统内部执行的 SQL 语句，`false` 表示用户执行的 SQL 语句。 @@ -172,11 +172,7 @@ Slow Query 基础信息： - `Storage_from_kv`：从 v8.5.5 开始引入，表示该语句是否从 TiKV 读取数据。 - `Storage_from_mpp`：从 v8.5.5 开始引入，表示该语句是否从 TiFlash 读取数据。 -## 相关变量 - -本节介绍慢查询日志相关的 Hint 与系统变量。 - -### 相关 Hint +## 相关 Hint 你可以通过 Hint `WRITE_SLOW_LOG` 强制控制输出慢查询日志。 @@ -189,31 +185,31 @@ Slow Query 基础信息： 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_threshold`](/system-variables.md#tidb_slow_log_threshold)：用于设置慢查询日志的阈值，执行时间超过阈值的 SQL 语句将被记录到慢查询日志中。默认值是 300 ms。 * [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-从-v900-版本开始引入)：用于定义慢查询日志的触发规则，支持多维度指标组合条件，以实现更加灵活和精细化的日志记录控制。该变量在 v9.0.0 版本中引入，逐步替代传统的单一阈值控制方式，即替代 `tidb_slow_log_threshold` 的使用。 * 如果未设置 `tidb_slow_log_rules`： - * 慢日志触发仍依赖 `tidb_slow_log_threshold`，`query_time` 阈值取自该变量，以保持向后兼容。 + * 慢查询日志触发仍依赖 `tidb_slow_log_threshold`，`query_time` 阈值取自该变量，以保持向后兼容。 * 如果已设置 `tidb_slow_log_rules`： * 配置的规则优先生效，`tidb_slow_log_threshold` 将被忽略。 * 若希望规则中仍包含 `query_time` 的触发条件，可在设置规则时指定。 * 规则匹配逻辑（多条规则之间采用 OR 关系）： - * Session 作用域规则：优先匹配，如果匹配成功，则打印慢日志。 + * Session 作用域规则：优先匹配，如果匹配成功，则打印慢查询日志。 * Global 作用域规则：仅在 Session 规则未匹配时考虑： * 若规则指定了 `ConnID` 并与当前 Session 的 `ConnID` 匹配，则使用该规则。 * 若规则未指定 `ConnID`（全局通用规则），则使用该规则。 * 显示变量的行为与普通系统变量一致。 - > **Tip** - > - > - `tidb_slow_log_rules` 用于替换单一阈值的方式，实现更灵活和精细化的慢查询日志控制，支持多维度指标组合条件。 - > - 在资源充足的测试环境（1 TiDB：16C/48G，3 TiKV：16C/48G）中，多次 sysbench 测试结果表明：当多维慢查询日志规则生成的慢查询日志量处于半小时内数百万级时，对性能影响较小；但若日志量达到千万级，则会导致 TPS、延迟出现明显下降。在业务负载较高或 CPU/内存接近瓶颈时，应谨慎配置 `tidb_slow_log_rules`，避免规则过宽导致日志洪泛。建议结合 `tidb_slow_log_max_per_sec` 限制日志打印速率，以降低对业务性能的影响。 + > **Tip** + > + > - `tidb_slow_log_rules` 用于替换单一阈值的方式，实现更灵活和精细化的慢查询日志控制，支持多维度指标组合条件。 + > - 在资源充足的测试环境（1 TiDB：16C/48G，3 TiKV：16C/48G）中，多次 sysbench 测试结果表明：当多维慢查询日志规则生成的慢查询日志量处于半小时内数百万级时，对性能影响较小；但若日志量达到千万级，则会导致 TPS、延迟出现明显下降。在业务负载较高或 CPU/内存接近瓶颈时，应谨慎配置 `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-从-v900-版本开始引入)：用于设置每秒打印慢日志的上限，默认值为 0。 - * 当值为 0 时，表示不限制每秒打印的慢日志数量。 - * 当值大于 0 时，TiDB 每秒最多打印指定数量的慢查询日志，超过部分将被丢弃，不会写入慢日志文件。 - * 建议在启用了 `tidb_slow_log_rules` 后配置该变量，以避免规则触发频繁打印慢日志。 +* [`tidb_slow_log_max_per_sec`](/system-variables.md#tidb_slow_log_max_per_sec-从-v900-版本开始引入)：用于设置每秒打印慢查询日志的上限，默认值为 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` 的示例如下： @@ -243,17 +239,17 @@ set @@tidb_enable_collect_execution_info=0; 更多详细信息，可以参见 [TiDB 专用系统变量和语法](/system-variables.md)。 -## 慢日志内存映射表 +## 慢查询日志内存映射表 -用户可通过查询 `INFORMATION_SCHEMA.SLOW_QUERY` 表来查询慢查询日志中的内容，表中列名和慢日志中字段名一一对应，表结构可查看 [`SLOW_QUERY` 表](/information-schema/information-schema-slow-query.md)中的介绍。 +用户可通过查询 `INFORMATION_SCHEMA.SLOW_QUERY` 表来查询慢查询日志中的内容，表中列名和慢查询日志中字段名一一对应，表结构可查看 [`SLOW_QUERY` 表](/information-schema/information-schema-slow-query.md)中的介绍。 > **注意：** > > 每次查询 `SLOW_QUERY` 表时，TiDB 都会去读取和解析一次当前的慢查询日志。 -TiDB 4.0 中，`SLOW_QUERY` 已经支持查询任意时间段的慢日志，即支持查询已经被 rotate 的慢日志文件的数据。用户查询时只需要指定 `TIME` 时间范围即可定位需要解析的慢日志文件。如果查询不指定时间范围，则仍然只解析当前的慢日志文件，示例如下： +TiDB 4.0 中，`SLOW_QUERY` 已经支持查询任意时间段的慢查询日志，即支持查询已经被 rotate 的慢查询日志文件的数据。用户查询时只需要指定 `TIME` 时间范围即可定位需要解析的慢查询日志文件。如果查询不指定时间范围，则仍然只解析当前的慢查询日志文件，示例如下： -不指定时间范围时，只会解析当前 TiDB 正在写入的慢日志文件的慢查询数据： +不指定时间范围时，只会解析当前 TiDB 正在写入的慢查询日志文件的慢查询数据： {{< copyable "sql" >}} @@ -272,7 +268,7 @@ from slow_query; +----------+----------------------------+----------------------------+ ``` -指定查询 `2020-03-10 00:00:00` 到 `2020-03-11 00:00:00` 时间范围后，会定位指定时间范围内的慢日志文件后解析慢查询数据： +指定查询 `2020-03-10 00:00:00` 到 `2020-03-11 00:00:00` 时间范围后，会定位指定时间范围内的慢查询日志文件后解析慢查询数据： {{< copyable "sql" >}} @@ -295,7 +291,7 @@ where time > '2020-03-10 00:00:00' > **注意：** > -> 如果指定时间范围内的慢日志文件被删除，或者并没有慢查询，则查询结果会返回空。 +> 如果指定时间范围内的慢查询日志文件被删除，或者并没有慢查询，则查询结果会返回空。 TiDB 4.0 中新增了 [`CLUSTER_SLOW_QUERY`](/information-schema/information-schema-slow-query.md#cluster_slow_query-table) 系统表，用来查询所有 TiDB 节点的慢查询信息，表结构在 `SLOW_QUERY` 的基础上多增加了 `INSTANCE` 列，表示该行慢查询信息来自的 TiDB 节点地址。使用方式和 [`SLOW_QUERY`](/information-schema/information-schema-slow-query.md) 系统表一样。 @@ -506,9 +502,9 @@ select instance, count(*) from information_schema.cluster_slow_query where time +---------------+----------+ ``` -### 查询仅出现在异常时间段的慢日志 +### 查询仅出现在异常时间段的慢查询日志 -假如发现 `2020-03-10 13:24:00` ~ `2020-03-10 13:27:00` 的 QPS 降低或者延迟上升等问题，可能是由于突然出现大查询导致的，可以用下面 SQL 查询仅出现在异常时间段的慢日志，其中 `2020-03-10 13:20:00` ~ `2020-03-10 13:23:00` 为正常时间段。 +假如发现 `2020-03-10 13:24:00` ~ `2020-03-10 13:27:00` 的 QPS 降低或者延迟上升等问题，可能是由于突然出现大查询导致的，可以用下面 SQL 查询仅出现在异常时间段的慢查询日志，其中 `2020-03-10 13:20:00` ~ `2020-03-10 13:23:00` 为正常时间段。 {{< copyable "sql" >}} @@ -559,7 +555,7 @@ min(prev_stmt) | digest | 24bd6d8a9b238086c9b8c3d240ad4ef32f79ce94cf5a468c0b8fe1eb5f8d03df ``` -## 解析其他的 TiDB 慢日志文件 +## 解析其他的 TiDB 慢查询日志文件 TiDB 通过 session 变量 `tidb_slow_query_file` 控制查询 `INFORMATION_SCHEMA.SLOW_QUERY` 时要读取和解析的文件，可通过修改改 session 变量的值来查询其他慢查询日志文件的内容： @@ -569,9 +565,9 @@ TiDB 通过 session 变量 `tidb_slow_query_file` 控制查询 `INFORMATION_SCHE set tidb_slow_query_file = "/path-to-log/tidb-slow.log" ``` -## 用 `pt-query-digest` 工具分析 TiDB 慢日志 +## 用 `pt-query-digest` 工具分析 TiDB 慢查询日志 -可以用 `pt-query-digest` 工具分析 TiDB 慢日志。 +可以用 `pt-query-digest` 工具分析 TiDB 慢查询日志。 > **注意：** > From 2b1534d230ff385016985046cfdbed4da3e22e8c Mon Sep 17 00:00:00 2001 From: lilin90 Date: Wed, 10 Dec 2025 11:07:48 +0800 Subject: [PATCH 19/43] Put two system variables in alphabetical order --- system-variables.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/system-variables.md b/system-variables.md index 0b587ac1c017..a69694b75924 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5062,16 +5062,15 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) > > 跳过字符检查可能会使 TiDB 检测不到应用写入的非法 UTF-8 字符，进一步导致执行 `ANALYZE` 时解码错误，以及引入其他未知的编码问题。如果应用不能保证写入字符串的合法性，不建议跳过该检查。 -### `tidb_slow_log_threshold` +### `tidb_slow_log_max_per_sec` 从 v9.0.0 版本开始引入 - 作用域：GLOBAL -- 是否持久化到集群：否，仅作用于当前连接的 TiDB 实例 +- 是否持久化到集群：是 - 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否 -- 默认值：`300` +- 默认值：`0` - 类型：整数型 -- 范围：`[-1, 9223372036854775807]` -- 单位：毫秒 -- 输出慢日志的耗时阈值，默认为 300 ms。如果查询耗时大于这个值，会视作一个慢查询，并记录到慢查询日志。注意，当日志的输出级别 [`log.level`](/tidb-configuration-file.md#level) 是 `"debug"` 时，所有查询都会记录到慢日志，不受该变量的限制。 +- 范围：`[0, 1000000]` +- 控制每个 TiDB 节点每秒打印慢日志的次数上限，默认值为 `0`。当该变量值为 `0` 时，表示不限制每个节点每秒打印的慢日志数量。当该变量值大于 `0` 时，会限制每个节点每秒打印的慢日志数量不超过该值，超过部分的慢日志将被丢弃，不会写入慢日志文件。该变量常与 [`tidb_slow_log_rules`](#tidb_slow_log_rules-从-v900-版本开始引入) 结合使用，以防止在高负载情况下产生过多的慢日志。 ### `tidb_slow_log_rules` 从 v9.0.0 版本开始引入 @@ -5086,15 +5085,16 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) > > 建议在启用 [`tidb_slow_log_rules`](#tidb_slow_log_rules-从-v900-版本开始引入) 后，同时配置 [`tidb_slow_log_max_per_sec`](#tidb_slow_log_max_per_sec-从-v900-版本开始引入)，以限制慢日志打印频率，防止基于规则的慢日志触发过于频繁。 -### `tidb_slow_log_max_per_sec` 从 v9.0.0 版本开始引入 +### `tidb_slow_log_threshold` - 作用域：GLOBAL -- 是否持久化到集群：是 +- 是否持久化到集群：否，仅作用于当前连接的 TiDB 实例 - 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否 -- 默认值：`0` +- 默认值：`300` - 类型：整数型 -- 范围：`[0, 1000000]` -- 控制每个 TiDB 节点每秒打印慢日志的次数上限，默认值为 `0`。当该变量值为 `0` 时，表示不限制每个节点每秒打印的慢日志数量。当该变量值大于 `0` 时，会限制每个节点每秒打印的慢日志数量不超过该值，超过部分的慢日志将被丢弃，不会写入慢日志文件。该变量常与 [`tidb_slow_log_rules`](#tidb_slow_log_rules-从-v900-版本开始引入) 结合使用，以防止在高负载情况下产生过多的慢日志。 +- 范围：`[-1, 9223372036854775807]` +- 单位：毫秒 +- 输出慢日志的耗时阈值，默认为 300 ms。如果查询耗时大于这个值，会视作一个慢查询，并记录到慢查询日志。注意，当日志的输出级别 [`log.level`](/tidb-configuration-file.md#level) 是 `"debug"` 时，所有查询都会记录到慢日志，不受该变量的限制。 ### `tidb_slow_query_file` From 58f2d549c70775f6aad96749149dd7cf884c6701 Mon Sep 17 00:00:00 2001 From: lilin90 Date: Wed, 10 Dec 2025 11:10:03 +0800 Subject: [PATCH 20/43] Update wording for consistency and clarity --- system-variables.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/system-variables.md b/system-variables.md index a69694b75924..a6bcbd6bc07a 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5070,7 +5070,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) - 默认值：`0` - 类型：整数型 - 范围：`[0, 1000000]` -- 控制每个 TiDB 节点每秒打印慢日志的次数上限，默认值为 `0`。当该变量值为 `0` 时，表示不限制每个节点每秒打印的慢日志数量。当该变量值大于 `0` 时，会限制每个节点每秒打印的慢日志数量不超过该值，超过部分的慢日志将被丢弃，不会写入慢日志文件。该变量常与 [`tidb_slow_log_rules`](#tidb_slow_log_rules-从-v900-版本开始引入) 结合使用，以防止在高负载情况下产生过多的慢日志。 +- 控制每个 TiDB 节点每秒打印慢查询日志的次数上限，默认值为 `0`。当该变量值为 `0` 时，表示不限制每个节点每秒打印的慢查询日志数量。当该变量值大于 `0` 时，会限制每个节点每秒打印的慢查询日志数量不超过该值，超过部分的慢查询日志将被丢弃，不会写入慢查询日志文件。该变量常与 [`tidb_slow_log_rules`](#tidb_slow_log_rules-从-v900-版本开始引入) 结合使用，以防止在高负载情况下产生过多的慢查询日志。 ### `tidb_slow_log_rules` 从 v9.0.0 版本开始引入 @@ -5079,11 +5079,11 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) - 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否 - 默认值："" - 类型：字符串 -- 用于定义慢日志的触发规则，支持基于多维度指标的组合条件，实现更加灵活和精细化的日志记录控制。 +- 用于定义慢查询日志的触发规则，支持基于多维度指标的组合条件，实现更加灵活和精细化的日志记录控制。 > **注意** > -> 建议在启用 [`tidb_slow_log_rules`](#tidb_slow_log_rules-从-v900-版本开始引入) 后，同时配置 [`tidb_slow_log_max_per_sec`](#tidb_slow_log_max_per_sec-从-v900-版本开始引入)，以限制慢日志打印频率，防止基于规则的慢日志触发过于频繁。 +> 建议在启用 [`tidb_slow_log_rules`](#tidb_slow_log_rules-从-v900-版本开始引入) 后，同时配置 [`tidb_slow_log_max_per_sec`](#tidb_slow_log_max_per_sec-从-v900-版本开始引入)，以限制慢查询日志打印频率，防止基于规则的慢查询日志触发过于频繁。 ### `tidb_slow_log_threshold` From ba25b4894e0156d1cdfb0dc65932b06c2ee75e3c Mon Sep 17 00:00:00 2001 From: lilin90 Date: Wed, 10 Dec 2025 11:10:58 +0800 Subject: [PATCH 21/43] Use a tip --- system-variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-variables.md b/system-variables.md index a6bcbd6bc07a..0e251d89bc10 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5081,7 +5081,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) - 类型：字符串 - 用于定义慢查询日志的触发规则，支持基于多维度指标的组合条件，实现更加灵活和精细化的日志记录控制。 -> **注意** +> **Tip** > > 建议在启用 [`tidb_slow_log_rules`](#tidb_slow_log_rules-从-v900-版本开始引入) 后，同时配置 [`tidb_slow_log_max_per_sec`](#tidb_slow_log_max_per_sec-从-v900-版本开始引入)，以限制慢查询日志打印频率，防止基于规则的慢查询日志触发过于频繁。 From 000a4667eb6cc0e0baa4c8296be2cbbae2ae2050 Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Mon, 15 Dec 2025 15:37:04 +0800 Subject: [PATCH 22/43] Update identify-slow-queries.md --- identify-slow-queries.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index c38ec70c25a5..3827762a9338 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -195,9 +195,9 @@ SELECT /*+ WRITE_SLOW_LOG */ count(*) FROM t t1, t t2 WHERE t1.a = t2.b; * 配置的规则优先生效，`tidb_slow_log_threshold` 将被忽略。 * 若希望规则中仍包含 `query_time` 的触发条件，可在设置规则时指定。 * 规则匹配逻辑（多条规则之间采用 OR 关系）： - * Session 作用域规则：优先匹配，如果匹配成功，则打印慢查询日志。 - * Global 作用域规则：仅在 Session 规则未匹配时考虑： - * 若规则指定了 `ConnID` 并与当前 Session 的 `ConnID` 匹配，则使用该规则。 + * SESSION 作用域规则：优先匹配，如果匹配成功，则打印慢查询日志。 + * GLOBAL 作用域规则：仅在 SESSION 作用域规则未匹配时考虑： + * 若规则指定了 `ConnID` 并与当前会话的 `ConnID` 匹配，则使用该规则。 * 若规则未指定 `ConnID`（全局通用规则），则使用该规则。 * 显示变量的行为与普通系统变量一致。 From e6b776b0d0402bd1e3fb4feaaa700cbc3a90286b Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Mon, 15 Dec 2025 16:09:40 +0800 Subject: [PATCH 23/43] Update system-variables.md --- system-variables.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/system-variables.md b/system-variables.md index 0e251d89bc10..83031e015fd4 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5070,7 +5070,8 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) - 默认值：`0` - 类型：整数型 - 范围：`[0, 1000000]` -- 控制每个 TiDB 节点每秒打印慢查询日志的次数上限，默认值为 `0`。当该变量值为 `0` 时，表示不限制每个节点每秒打印的慢查询日志数量。当该变量值大于 `0` 时，会限制每个节点每秒打印的慢查询日志数量不超过该值，超过部分的慢查询日志将被丢弃，不会写入慢查询日志文件。该变量常与 [`tidb_slow_log_rules`](#tidb_slow_log_rules-从-v900-版本开始引入) 结合使用，以防止在高负载情况下产生过多的慢查询日志。 +- 控制每个 TiDB 节点每秒打印慢查询日志的次数上限，默认值为 `0`。当该变量值为 `0` 时，表示不限制每个节点每秒打印的慢查询日志数量。当该变量值大于 `0` 时，会限制每个节点每秒打印的慢查询日志数量不超过该值，超过部分的慢查询日志将被丢弃，不会写入慢查询日志文件。 +- 该变量常与 [`tidb_slow_log_rules`](#tidb_slow_log_rules-从-v900-版本开始引入) 结合使用，以防止在高负载情况下产生过多的慢查询日志。 ### `tidb_slow_log_rules` 从 v9.0.0 版本开始引入 From cdbbc438d9e7b05f5ad802a2d13ce32154a7e5c4 Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Mon, 15 Dec 2025 16:11:04 +0800 Subject: [PATCH 24/43] Update system-variables.md --- system-variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-variables.md b/system-variables.md index 83031e015fd4..e5e6aa834483 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5082,7 +5082,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) - 类型：字符串 - 用于定义慢查询日志的触发规则，支持基于多维度指标的组合条件，实现更加灵活和精细化的日志记录控制。 -> **Tip** +> **Tip：** > > 建议在启用 [`tidb_slow_log_rules`](#tidb_slow_log_rules-从-v900-版本开始引入) 后，同时配置 [`tidb_slow_log_max_per_sec`](#tidb_slow_log_max_per_sec-从-v900-版本开始引入)，以限制慢查询日志打印频率，防止基于规则的慢查询日志触发过于频繁。 From 585956362445f6101121a5cdb7919e35c205efe5 Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Mon, 15 Dec 2025 16:13:30 +0800 Subject: [PATCH 25/43] Update system-variables.md --- system-variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-variables.md b/system-variables.md index e5e6aa834483..477c3f4dd895 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5084,7 +5084,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) > **Tip：** > -> 建议在启用 [`tidb_slow_log_rules`](#tidb_slow_log_rules-从-v900-版本开始引入) 后，同时配置 [`tidb_slow_log_max_per_sec`](#tidb_slow_log_max_per_sec-从-v900-版本开始引入)，以限制慢查询日志打印频率，防止基于规则的慢查询日志触发过于频繁。 +> 建议在启用 `tidb_slow_log_rules` 后，同时配置 [`tidb_slow_log_max_per_sec`](#tidb_slow_log_max_per_sec-从-v900-版本开始引入)，以限制慢查询日志打印频率，防止基于规则的慢查询日志触发过于频繁。 ### `tidb_slow_log_threshold` From 13d097ed9d3992f1294826be125220989e4f3783 Mon Sep 17 00:00:00 2001 From: Lynn Date: Tue, 16 Dec 2025 09:46:13 +0800 Subject: [PATCH 26/43] Update identify-slow-queries.md Co-authored-by: xixirangrang --- identify-slow-queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index 3827762a9338..9ee66207e441 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -199,7 +199,7 @@ SELECT /*+ WRITE_SLOW_LOG */ count(*) FROM t t1, t t2 WHERE t1.a = t2.b; * GLOBAL 作用域规则：仅在 SESSION 作用域规则未匹配时考虑： * 若规则指定了 `ConnID` 并与当前会话的 `ConnID` 匹配，则使用该规则。 * 若规则未指定 `ConnID`（全局通用规则），则使用该规则。 - * 显示变量的行为与普通系统变量一致。 + * 使用 `SHOW VARIABLES`、`SELECT @@GLOBAL.tidb_slow_log_rules`、 `SELECT @@SESSION.tidb_slow_log_rules` 显示该变量的行为与其他系统变量一致。 > **Tip** > From 6208efdbfd520242430d4fa80f180a328c9bf320 Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Tue, 16 Dec 2025 09:46:48 +0800 Subject: [PATCH 27/43] Update system-variables.md --- system-variables.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/system-variables.md b/system-variables.md index 477c3f4dd895..7029f34a187c 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5070,7 +5070,9 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) - 默认值：`0` - 类型：整数型 - 范围：`[0, 1000000]` -- 控制每个 TiDB 节点每秒打印慢查询日志的次数上限，默认值为 `0`。当该变量值为 `0` 时，表示不限制每个节点每秒打印的慢查询日志数量。当该变量值大于 `0` 时，会限制每个节点每秒打印的慢查询日志数量不超过该值，超过部分的慢查询日志将被丢弃，不会写入慢查询日志文件。 +- 控制每个 TiDB 节点每秒打印慢查询日志的次数上限。 + - 当值为 `0` （默认值）时，表示不限制每秒打印的慢查询日志数量。 + - 当值大于 `0` 时，TiDB 每秒最多打印指定数量的慢查询日志，超过部分将被丢弃，不会写入慢查询日志文件。 - 该变量常与 [`tidb_slow_log_rules`](#tidb_slow_log_rules-从-v900-版本开始引入) 结合使用，以防止在高负载情况下产生过多的慢查询日志。 ### `tidb_slow_log_rules` 从 v9.0.0 版本开始引入 From a5440a0e4620e2620305cf75c7f68ac6275be799 Mon Sep 17 00:00:00 2001 From: Lynn Date: Tue, 16 Dec 2025 15:39:58 +0800 Subject: [PATCH 28/43] Update identify-slow-queries.md Co-authored-by: huoyao1125 <90880576+huoyao1125@users.noreply.github.com> --- identify-slow-queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index 9ee66207e441..0e4fc29e8ca6 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -193,7 +193,7 @@ SELECT /*+ WRITE_SLOW_LOG */ count(*) FROM t t1, t t2 WHERE t1.a = t2.b; * 慢查询日志触发仍依赖 `tidb_slow_log_threshold`，`query_time` 阈值取自该变量，以保持向后兼容。 * 如果已设置 `tidb_slow_log_rules`： * 配置的规则优先生效，`tidb_slow_log_threshold` 将被忽略。 - * 若希望规则中仍包含 `query_time` 的触发条件，可在设置规则时指定。 + * 若希望规则中仍使用 `SQL 执行时间` 作为输出慢日志的条件之一，可在设置规则时使用`query_time` 并设置阈值。 * 规则匹配逻辑（多条规则之间采用 OR 关系）： * SESSION 作用域规则：优先匹配，如果匹配成功，则打印慢查询日志。 * GLOBAL 作用域规则：仅在 SESSION 作用域规则未匹配时考虑： From ceed1069f32b2d42d11403c5ac231bc95e7115f0 Mon Sep 17 00:00:00 2001 From: Lynn Date: Tue, 16 Dec 2025 15:41:26 +0800 Subject: [PATCH 29/43] Update identify-slow-queries.md Co-authored-by: huoyao1125 <90880576+huoyao1125@users.noreply.github.com> --- identify-slow-queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index 0e4fc29e8ca6..e5bbb081f690 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -190,7 +190,7 @@ 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-从-v900-版本开始引入)：用于定义慢查询日志的触发规则，支持多维度指标组合条件，以实现更加灵活和精细化的日志记录控制。该变量在 v9.0.0 版本中引入，逐步替代传统的单一阈值控制方式，即替代 `tidb_slow_log_threshold` 的使用。 * 如果未设置 `tidb_slow_log_rules`： - * 慢查询日志触发仍依赖 `tidb_slow_log_threshold`，`query_time` 阈值取自该变量，以保持向后兼容。 + * 慢查询日志触发仍依赖 `tidb_slow_log_threshold`。注：`query_time` 阈值的含义同该变量，均表示 SQL 执行时长阈值，以保持向后兼容。 * 如果已设置 `tidb_slow_log_rules`： * 配置的规则优先生效，`tidb_slow_log_threshold` 将被忽略。 * 若希望规则中仍使用 `SQL 执行时间` 作为输出慢日志的条件之一，可在设置规则时使用`query_time` 并设置阈值。 From ddaf9f6c2db695bd55d3eccebd7499bbdf7d5d11 Mon Sep 17 00:00:00 2001 From: Lynn Date: Wed, 17 Dec 2025 16:34:34 +0800 Subject: [PATCH 30/43] *: add rule items --- identify-slow-queries.md | 49 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 48 insertions(+), 1 deletion(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index e5bbb081f690..d42946b5c711 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -188,7 +188,30 @@ 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-从-v900-版本开始引入)：用于定义慢查询日志的触发规则，支持多维度指标组合条件，以实现更加灵活和精细化的日志记录控制。该变量在 v9.0.0 版本中引入，逐步替代传统的单一阈值控制方式，即替代 `tidb_slow_log_threshold` 的使用。 +* [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-从-v900-版本开始引入)：用于定义慢查询日志的触发规则，支持多维度指标组合条件，以实现更加灵活和精细化的日志记录控制。该变量在 v9.0.0 版本中引入，逐步替代传统的单一阈值控制方式，即替代 `tidb_slow_log_threshold` 的使用。该变量下，支持把以下字段作为筛选条件，来设置输出慢查询日志的条件： + * 支持的筛选字段(下面字段说明可以参考：[字段含义说明](/#字段含义说明))： + * Slow Query 基础信息： + * `Query_time`、`Parse_time`、`Compile_time`、`Optimize_time`、`Wait_TS`、`Rewrite_time` + * `Digest`、`Plan_digest`、`Is_internal`、`Succ` + * `Exec_retry_count`、`Backoff_time`、`Write_sql_response_total` + * 和事务执行相关的字段： + * `Prewrite_time`、`Commit_time`、`Write_keys`、`Write_size`、`Prewrite_region` + * 和 SQL 执行的用户相关的字段： + * `Conn_ID`、`DB`、`Session_alias` + * 和 TiKV Coprocessor Task 相关的字段： + * `Process_time`、`Total_keys`、`Process_keys`、`Num_cop_tasks` + * 和内存使用相关的字段： + * `Mem_max` + * 和硬盘使用相关的字段： + * `Disk_max` + * 和资源管控相关的字段： + * `Resource_group` + * 和网络传输相关的字段： + * `KV_total`、`PD_total` + * `Unpacked_bytes_sent_tikv_total`、`Unpacked_bytes_received_tikv_total` + * `Unpacked_bytes_sent_tikv_cross_zone`、`Unpacked_bytes_received_tikv_cross_zone` + * `Unpacked_bytes_sent_tiflash_total`、`Unpacked_bytes_received_tiflash_total` + * `Unpacked_bytes_sent_tiflash_cross_zone`、`Unpacked_bytes_received_tiflash_cross_zone` * 如果未设置 `tidb_slow_log_rules`： * 慢查询日志触发仍依赖 `tidb_slow_log_threshold`。注：`query_time` 阈值的含义同该变量，均表示 SQL 执行时长阈值，以保持向后兼容。 * 如果已设置 `tidb_slow_log_rules`： @@ -200,6 +223,30 @@ SELECT /*+ WRITE_SLOW_LOG */ count(*) FROM t t1, t t2 WHERE t1.a = t2.b; * 若规则指定了 `ConnID` 并与当前会话的 `ConnID` 匹配，则使用该规则。 * 若规则未指定 `ConnID`（全局通用规则），则使用该规则。 * 使用 `SHOW VARIABLES`、`SELECT @@GLOBAL.tidb_slow_log_rules`、 `SELECT @@SESSION.tidb_slow_log_rules` 显示该变量的行为与其他系统变量一致。 + * 使用示例： + * 标准格式（SESSION 作用域）： + + ```sql + SET SESSION tidb_slow_log_rules = 'Query_time: 500, Is_internal: false'; + ``` + + * 错误格式（SESSION 作用域不支持 ConnID）： + + ```sql + SET SESSION tidb_slow_log_rules = 'ConnID: 12, Query_time: 500, Is_internal: false'; + ``` + + * 全局规则（适用于所有连接）： + + ```sql + SET GLOBAL tidb_slow_log_rules = 'Query_time: 500, Is_internal: false'; + ``` + + * 指定特定连接的全局规则（分别适用于 `ConnID:11` 和 `ConnID:11` 的两个连接）： + + ```sql + SET GLOBAL tidb_slow_log_rules = 'ConnID: 11, Query_time: 500, Is_internal: false; ConnID: 12, Query_time: 600, Process_time: 300, DB: db1'; + ``` > **Tip** > From 7c6364a578c81d28fd1a235de6f4befa406857b8 Mon Sep 17 00:00:00 2001 From: Lynn Date: Wed, 17 Dec 2025 16:35:47 +0800 Subject: [PATCH 31/43] Update identify-slow-queries.md Co-authored-by: huoyao1125 <90880576+huoyao1125@users.noreply.github.com> --- identify-slow-queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index d42946b5c711..df3bcff94a51 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -174,7 +174,7 @@ Slow Query 基础信息： ## 相关 Hint -你可以通过 Hint `WRITE_SLOW_LOG` 强制控制输出慢查询日志。 +自 v9.0.0 版本中引入 hint，你可以通过 Hint `WRITE_SLOW_LOG` 强制控制输出慢查询日志。 - 该 Hint 不受任何阈值或触发规则限制，即无论该 SQL 查询是否达到慢查询日志打印阈值，都会打印慢查询日志。 - 目前只支持强制开启打印慢查询日志，暂不支持通过 `WRITE_SLOW_LOG(FALSE)` 强制关闭打印慢查询日志。 From 2f84b6820126be31d19de2f3e2ccd30f02df853b Mon Sep 17 00:00:00 2001 From: Lynn Date: Tue, 23 Dec 2025 10:15:12 +0800 Subject: [PATCH 32/43] Update identify-slow-queries.md Co-authored-by: xixirangrang --- identify-slow-queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index df3bcff94a51..171024e73f6e 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -174,7 +174,7 @@ Slow Query 基础信息： ## 相关 Hint -自 v9.0.0 版本中引入 hint，你可以通过 Hint `WRITE_SLOW_LOG` 强制控制输出慢查询日志。 +自 v9.0.0 版本中引入 Hint，你可以使用 `WRITE_SLOW_LOG` Hint 强制 TiDB 将特定 SQL 的执行信息输出至慢查询日志，无论其执行时长是否达到阈值。这有助于捕捉 SQL 执行时的详细元数据，例如执行计划和资源消耗。例如，在出现偶发性能波动问题时，某些 SQL 仅在特定条件下（如数据量突增或索引失效）才会变慢，而平时执行很快，因此难以通过默认阈值捕获。这种情况下，可以通过预先在业务 SQL 中添加该 Hint，确保在问题复现的瞬间，系统能完整记录下该次执行的详细信息。 - 该 Hint 不受任何阈值或触发规则限制，即无论该 SQL 查询是否达到慢查询日志打印阈值，都会打印慢查询日志。 - 目前只支持强制开启打印慢查询日志，暂不支持通过 `WRITE_SLOW_LOG(FALSE)` 强制关闭打印慢查询日志。 From 81b6d224d375d56df50da4a7441966a278ed2039 Mon Sep 17 00:00:00 2001 From: houfaxin Date: Wed, 7 Jan 2026 14:35:18 +0800 Subject: [PATCH 33/43] Update identify-slow-queries.md --- identify-slow-queries.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index 171024e73f6e..4aff4d4ec7e1 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -188,25 +188,25 @@ 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-从-v900-版本开始引入)：用于定义慢查询日志的触发规则，支持多维度指标组合条件，以实现更加灵活和精细化的日志记录控制。该变量在 v9.0.0 版本中引入，逐步替代传统的单一阈值控制方式，即替代 `tidb_slow_log_threshold` 的使用。该变量下，支持把以下字段作为筛选条件，来设置输出慢查询日志的条件： - * 支持的筛选字段(下面字段说明可以参考：[字段含义说明](/#字段含义说明))： +* [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-从-v900-版本开始引入)：用于定义慢查询日志的触发规则，支持多维度指标组合条件，以实现更加灵活和精细化的日志记录控制。该变量在 v9.0.0 版本中引入，逐步替代传统的单一阈值控制方式，即替代 `tidb_slow_log_threshold` 的使用。该变量下，支持把以下字段作为筛选条件，来设置输出慢查询日志的条件。详情请参考[字段含义说明](#字段含义说明)： + - 支持的筛选字段： * Slow Query 基础信息： * `Query_time`、`Parse_time`、`Compile_time`、`Optimize_time`、`Wait_TS`、`Rewrite_time` * `Digest`、`Plan_digest`、`Is_internal`、`Succ` * `Exec_retry_count`、`Backoff_time`、`Write_sql_response_total` - * 和事务执行相关的字段： + * 事务执行相关的字段： * `Prewrite_time`、`Commit_time`、`Write_keys`、`Write_size`、`Prewrite_region` - * 和 SQL 执行的用户相关的字段： + * SQL 执行的用户相关的字段： * `Conn_ID`、`DB`、`Session_alias` - * 和 TiKV Coprocessor Task 相关的字段： + * TiKV Coprocessor Task 相关的字段： * `Process_time`、`Total_keys`、`Process_keys`、`Num_cop_tasks` - * 和内存使用相关的字段： + * 内存使用相关的字段： * `Mem_max` - * 和硬盘使用相关的字段： + * 硬盘使用相关的字段： * `Disk_max` - * 和资源管控相关的字段： + * 资源管控相关的字段： * `Resource_group` - * 和网络传输相关的字段： + * 网络传输相关的字段： * `KV_total`、`PD_total` * `Unpacked_bytes_sent_tikv_total`、`Unpacked_bytes_received_tikv_total` * `Unpacked_bytes_sent_tikv_cross_zone`、`Unpacked_bytes_received_tikv_cross_zone` From 61992f05175fe9370d1a10a3df25eea8a1af3797 Mon Sep 17 00:00:00 2001 From: houfaxin Date: Wed, 7 Jan 2026 15:15:28 +0800 Subject: [PATCH 34/43] Update identify-slow-queries.md --- identify-slow-queries.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index 4aff4d4ec7e1..3190944bb280 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -188,7 +188,7 @@ 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-从-v900-版本开始引入)：用于定义慢查询日志的触发规则，支持多维度指标组合条件，以实现更加灵活和精细化的日志记录控制。该变量在 v9.0.0 版本中引入，逐步替代传统的单一阈值控制方式，即替代 `tidb_slow_log_threshold` 的使用。该变量下，支持把以下字段作为筛选条件，来设置输出慢查询日志的条件。详情请参考[字段含义说明](#字段含义说明)： +* [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-从-v900-版本开始引入)：用于定义慢查询日志的触发规则，支持多维度指标组合条件，以实现更加灵活和精细化的日志记录控制。该变量在 v9.0.0 版本中引入，逐步替代传统的单一阈值控制方式，即替代 `tidb_slow_log_threshold` 的使用。该变量支持将以下字段作为筛选条件，设置输出慢查询日志的条件。详情请参考[字段含义说明](#字段含义说明)。 - 支持的筛选字段： * Slow Query 基础信息： * `Query_time`、`Parse_time`、`Compile_time`、`Optimize_time`、`Wait_TS`、`Rewrite_time` @@ -230,7 +230,7 @@ SELECT /*+ WRITE_SLOW_LOG */ count(*) FROM t t1, t t2 WHERE t1.a = t2.b; SET SESSION tidb_slow_log_rules = 'Query_time: 500, Is_internal: false'; ``` - * 错误格式（SESSION 作用域不支持 ConnID）： + * 错误格式（SESSION 作用域不支持 `ConnID`）： ```sql SET SESSION tidb_slow_log_rules = 'ConnID: 12, Query_time: 500, Is_internal: false'; @@ -248,14 +248,14 @@ SELECT /*+ WRITE_SLOW_LOG */ count(*) FROM t t1, t t2 WHERE t1.a = t2.b; SET GLOBAL tidb_slow_log_rules = 'ConnID: 11, Query_time: 500, Is_internal: false; ConnID: 12, Query_time: 600, Process_time: 300, DB: db1'; ``` - > **Tip** + > **Tip:** > > - `tidb_slow_log_rules` 用于替换单一阈值的方式，实现更灵活和精细化的慢查询日志控制，支持多维度指标组合条件。 > - 在资源充足的测试环境（1 TiDB：16C/48G，3 TiKV：16C/48G）中，多次 sysbench 测试结果表明：当多维慢查询日志规则生成的慢查询日志量处于半小时内数百万级时，对性能影响较小；但若日志量达到千万级，则会导致 TPS、延迟出现明显下降。在业务负载较高或 CPU/内存接近瓶颈时，应谨慎配置 `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-从-v900-版本开始引入)：用于设置每秒打印慢查询日志的上限，默认值为 0。 - * 当值为 0 时，表示不限制每秒打印的慢查询日志数量。 - * 当值大于 0 时，TiDB 每秒最多打印指定数量的慢查询日志，超过部分将被丢弃，不会写入慢查询日志文件。 +* [`tidb_slow_log_max_per_sec`](/system-variables.md#tidb_slow_log_max_per_sec-从-v900-版本开始引入)：用于设置每秒打印慢查询日志的上限，默认值为 `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`，即关闭该功能。 @@ -276,8 +276,6 @@ SELECT /*+ WRITE_SLOW_LOG */ count(*) FROM t t1, t t2 WHERE t1.a = t2.b; 在性能测试中可以关闭自动收集算子的执行信息： -{{< copyable "sql" >}} - ```sql set @@tidb_enable_collect_execution_info=0; ``` From b686f71b92513e4ba62b04f7f585a952fa341a58 Mon Sep 17 00:00:00 2001 From: Lynn Date: Tue, 20 Jan 2026 16:44:00 +0800 Subject: [PATCH 35/43] Update identify-slow-queries.md Co-authored-by: Lilian Lee --- identify-slow-queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index 3190944bb280..60ba064b796d 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -174,7 +174,7 @@ Slow Query 基础信息： ## 相关 Hint -自 v9.0.0 版本中引入 Hint，你可以使用 `WRITE_SLOW_LOG` Hint 强制 TiDB 将特定 SQL 的执行信息输出至慢查询日志，无论其执行时长是否达到阈值。这有助于捕捉 SQL 执行时的详细元数据，例如执行计划和资源消耗。例如，在出现偶发性能波动问题时，某些 SQL 仅在特定条件下（如数据量突增或索引失效）才会变慢，而平时执行很快，因此难以通过默认阈值捕获。这种情况下，可以通过预先在业务 SQL 中添加该 Hint，确保在问题复现的瞬间，系统能完整记录下该次执行的详细信息。 +从 v9.0.0 开始，你可以使用 `WRITE_SLOW_LOG` Hint。该 Hint 用于强制 TiDB 将特定 SQL 的执行信息输出至慢查询日志，无论其执行时长是否达到阈值。这有助于捕获 SQL 执行过程中的详细元数据，如执行计划和资源消耗。例如，在出现偶发性能抖动问题时，某些 SQL 仅在特定条件下（如数据量突增或索引失效）才会变慢，而平时执行速度很快，因此难以通过默认的慢查询阈值捕获。这种情况下，可以预先在业务 SQL 中添加 `WRITE_SLOW_LOG` Hint，确保在问题复现的瞬间，系统能完整记录下该次 SQL 执行的详细信息。 - 该 Hint 不受任何阈值或触发规则限制，即无论该 SQL 查询是否达到慢查询日志打印阈值，都会打印慢查询日志。 - 目前只支持强制开启打印慢查询日志，暂不支持通过 `WRITE_SLOW_LOG(FALSE)` 强制关闭打印慢查询日志。 From 203863c20b0d2d55f0be4aa043d2321ddd222acf Mon Sep 17 00:00:00 2001 From: Lynn Date: Tue, 20 Jan 2026 16:44:22 +0800 Subject: [PATCH 36/43] Update identify-slow-queries.md Co-authored-by: Lilian Lee --- identify-slow-queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index 60ba064b796d..9fdc9018c7b8 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -216,7 +216,7 @@ SELECT /*+ WRITE_SLOW_LOG */ count(*) FROM t t1, t t2 WHERE t1.a = t2.b; * 慢查询日志触发仍依赖 `tidb_slow_log_threshold`。注：`query_time` 阈值的含义同该变量，均表示 SQL 执行时长阈值，以保持向后兼容。 * 如果已设置 `tidb_slow_log_rules`： * 配置的规则优先生效，`tidb_slow_log_threshold` 将被忽略。 - * 若希望规则中仍使用 `SQL 执行时间` 作为输出慢日志的条件之一，可在设置规则时使用`query_time` 并设置阈值。 + * 若希望规则中仍使用 SQL 执行时间作为输出慢日志的条件之一，可在设置规则时使用`query_time` 并设置阈值。 * 规则匹配逻辑（多条规则之间采用 OR 关系）： * SESSION 作用域规则：优先匹配，如果匹配成功，则打印慢查询日志。 * GLOBAL 作用域规则：仅在 SESSION 作用域规则未匹配时考虑： From 16dcb952505d42e78c886956cd268fca02b09181 Mon Sep 17 00:00:00 2001 From: Lynn Date: Tue, 20 Jan 2026 16:44:31 +0800 Subject: [PATCH 37/43] Update identify-slow-queries.md Co-authored-by: Lilian Lee --- identify-slow-queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index 9fdc9018c7b8..8c1a2d33beee 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -222,7 +222,7 @@ SELECT /*+ WRITE_SLOW_LOG */ count(*) FROM t t1, t t2 WHERE t1.a = t2.b; * GLOBAL 作用域规则：仅在 SESSION 作用域规则未匹配时考虑： * 若规则指定了 `ConnID` 并与当前会话的 `ConnID` 匹配，则使用该规则。 * 若规则未指定 `ConnID`（全局通用规则），则使用该规则。 - * 使用 `SHOW VARIABLES`、`SELECT @@GLOBAL.tidb_slow_log_rules`、 `SELECT @@SESSION.tidb_slow_log_rules` 显示该变量的行为与其他系统变量一致。 + * 使用 `SHOW VARIABLES`、`SELECT @@GLOBAL.tidb_slow_log_rules`、`SELECT @@SESSION.tidb_slow_log_rules` 显示该变量的行为与其他系统变量一致。 * 使用示例： * 标准格式（SESSION 作用域）： From 38f87d86b851cc37bbc8990d73d9f6848c8d7ee2 Mon Sep 17 00:00:00 2001 From: Lynn Date: Tue, 20 Jan 2026 17:17:18 +0800 Subject: [PATCH 38/43] Update identify-slow-queries.md Co-authored-by: Lilian Lee --- identify-slow-queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index 8c1a2d33beee..2ec874829940 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -251,7 +251,7 @@ SELECT /*+ WRITE_SLOW_LOG */ count(*) FROM t t1, t t2 WHERE t1.a = t2.b; > **Tip:** > > - `tidb_slow_log_rules` 用于替换单一阈值的方式，实现更灵活和精细化的慢查询日志控制，支持多维度指标组合条件。 - > - 在资源充足的测试环境（1 TiDB：16C/48G，3 TiKV：16C/48G）中，多次 sysbench 测试结果表明：当多维慢查询日志规则生成的慢查询日志量处于半小时内数百万级时，对性能影响较小；但若日志量达到千万级，则会导致 TPS、延迟出现明显下降。在业务负载较高或 CPU/内存接近瓶颈时，应谨慎配置 `tidb_slow_log_rules`，避免规则过宽导致日志洪泛。建议结合 `tidb_slow_log_max_per_sec` 限制日志打印速率，以降低对业务性能的影响。 + > - 在资源充足的测试环境（1 个 TiDB 节点，16 核 CPU、48 GiB 内存；3 个 TiKV 节点，每个 16 核 CPU、48 GiB 内存）中，多次 sysbench 测试结果表明：当多维慢查询日志规则在 30 分钟内生成数百万条慢查询日志时，对性能影响较小；但当日志量达到千万级时，TPS 会明显下降，延迟也会显著增加。在业务负载较高或 CPU、内存资源接近瓶颈的情况下，应谨慎配置 `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-从-v900-版本开始引入)：用于设置每秒打印慢查询日志的上限，默认值为 `0`。 * 当值为 `0` 时，表示不限制每秒打印的慢查询日志数量。 From 2575ae780cdf2c28ca8b32f48eb3f3a22f98c29e Mon Sep 17 00:00:00 2001 From: Lynn Date: Tue, 20 Jan 2026 17:17:41 +0800 Subject: [PATCH 39/43] Update system-variables.md Co-authored-by: Lilian Lee --- system-variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-variables.md b/system-variables.md index 7029f34a187c..415cb86e445c 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5070,7 +5070,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) - 默认值：`0` - 类型：整数型 - 范围：`[0, 1000000]` -- 控制每个 TiDB 节点每秒打印慢查询日志的次数上限。 +- 控制每个 TiDB 节点每秒打印的慢查询日志的数量上限。 - 当值为 `0` （默认值）时，表示不限制每秒打印的慢查询日志数量。 - 当值大于 `0` 时，TiDB 每秒最多打印指定数量的慢查询日志，超过部分将被丢弃，不会写入慢查询日志文件。 - 该变量常与 [`tidb_slow_log_rules`](#tidb_slow_log_rules-从-v900-版本开始引入) 结合使用，以防止在高负载情况下产生过多的慢查询日志。 From 20e5247ad9d8175dba2851cd5cf7571519015299 Mon Sep 17 00:00:00 2001 From: Lynn Date: Tue, 20 Jan 2026 17:18:18 +0800 Subject: [PATCH 40/43] Update identify-slow-queries.md Co-authored-by: Lilian Lee --- identify-slow-queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index 2ec874829940..9adaac8d1250 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -253,7 +253,7 @@ SELECT /*+ WRITE_SLOW_LOG */ count(*) FROM t t1, t t2 WHERE t1.a = t2.b; > - `tidb_slow_log_rules` 用于替换单一阈值的方式，实现更灵活和精细化的慢查询日志控制，支持多维度指标组合条件。 > - 在资源充足的测试环境（1 个 TiDB 节点，16 核 CPU、48 GiB 内存；3 个 TiKV 节点，每个 16 核 CPU、48 GiB 内存）中，多次 sysbench 测试结果表明：当多维慢查询日志规则在 30 分钟内生成数百万条慢查询日志时，对性能影响较小；但当日志量达到千万级时，TPS 会明显下降，延迟也会显著增加。在业务负载较高或 CPU、内存资源接近瓶颈的情况下，应谨慎配置 `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-从-v900-版本开始引入)：用于设置每秒打印慢查询日志的上限，默认值为 `0`。 +* [`tidb_slow_log_max_per_sec`](/system-variables.md#tidb_slow_log_max_per_sec-从-v900-版本开始引入)：用于设置每秒打印慢查询日志数量的上限，默认值为 `0`。 * 当值为 `0` 时，表示不限制每秒打印的慢查询日志数量。 * 当值大于 `0` 时，TiDB 每秒最多打印指定数量的慢查询日志，超过部分将被丢弃，不会写入慢查询日志文件。 * 建议在启用了 `tidb_slow_log_rules` 后配置该变量，以避免规则触发频繁打印慢查询日志。 From 1cc821a03d3975365545c5e3df3ac290d197013f Mon Sep 17 00:00:00 2001 From: Lynn Date: Tue, 20 Jan 2026 17:20:12 +0800 Subject: [PATCH 41/43] Update identify-slow-queries.md Co-authored-by: Lilian Lee --- identify-slow-queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index 9adaac8d1250..b46ff92f50aa 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -256,7 +256,7 @@ SELECT /*+ WRITE_SLOW_LOG */ count(*) FROM t t1, t t2 WHERE t1.a = t2.b; * [`tidb_slow_log_max_per_sec`](/system-variables.md#tidb_slow_log_max_per_sec-从-v900-版本开始引入)：用于设置每秒打印慢查询日志数量的上限，默认值为 `0`。 * 当值为 `0` 时，表示不限制每秒打印的慢查询日志数量。 * 当值大于 `0` 时，TiDB 每秒最多打印指定数量的慢查询日志，超过部分将被丢弃，不会写入慢查询日志文件。 - * 建议在启用了 `tidb_slow_log_rules` 后配置该变量，以避免规则触发频繁打印慢查询日志。 + * 建议在启用了 `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` 的示例如下： From ffcad73a11a081bbd0c566853baca2f3362d8093 Mon Sep 17 00:00:00 2001 From: Lilian Lee Date: Tue, 20 Jan 2026 17:30:23 +0800 Subject: [PATCH 42/43] Update Tip format --- system-variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-variables.md b/system-variables.md index 415cb86e445c..6765625e4e2c 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5084,7 +5084,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) - 类型：字符串 - 用于定义慢查询日志的触发规则，支持基于多维度指标的组合条件，实现更加灵活和精细化的日志记录控制。 -> **Tip：** +> **Tip:** > > 建议在启用 `tidb_slow_log_rules` 后，同时配置 [`tidb_slow_log_max_per_sec`](#tidb_slow_log_max_per_sec-从-v900-版本开始引入)，以限制慢查询日志打印频率，防止基于规则的慢查询日志触发过于频繁。 From 51a7ff3c5fbfc3978bead9afaac9ebf377cef093 Mon Sep 17 00:00:00 2001 From: Lynn Date: Tue, 10 Mar 2026 13:41:46 +0800 Subject: [PATCH 43/43] docs: adjust slow log version markers for release-8.5 --- identify-slow-queries.md | 6 +++--- system-variables.md | 8 ++++---- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/identify-slow-queries.md b/identify-slow-queries.md index b46ff92f50aa..2d0ea5e6a273 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -174,7 +174,7 @@ Slow Query 基础信息： ## 相关 Hint -从 v9.0.0 开始，你可以使用 `WRITE_SLOW_LOG` Hint。该 Hint 用于强制 TiDB 将特定 SQL 的执行信息输出至慢查询日志，无论其执行时长是否达到阈值。这有助于捕获 SQL 执行过程中的详细元数据，如执行计划和资源消耗。例如，在出现偶发性能抖动问题时，某些 SQL 仅在特定条件下（如数据量突增或索引失效）才会变慢，而平时执行速度很快，因此难以通过默认的慢查询阈值捕获。这种情况下，可以预先在业务 SQL 中添加 `WRITE_SLOW_LOG` Hint，确保在问题复现的瞬间，系统能完整记录下该次 SQL 执行的详细信息。 +从 v8.5.6 开始，你可以使用 `WRITE_SLOW_LOG` Hint。该 Hint 用于强制 TiDB 将特定 SQL 的执行信息输出至慢查询日志，无论其执行时长是否达到阈值。这有助于捕获 SQL 执行过程中的详细元数据，如执行计划和资源消耗。例如，在出现偶发性能抖动问题时，某些 SQL 仅在特定条件下（如数据量突增或索引失效）才会变慢，而平时执行速度很快，因此难以通过默认的慢查询阈值捕获。这种情况下，可以预先在业务 SQL 中添加 `WRITE_SLOW_LOG` Hint，确保在问题复现的瞬间，系统能完整记录下该次 SQL 执行的详细信息。 - 该 Hint 不受任何阈值或触发规则限制，即无论该 SQL 查询是否达到慢查询日志打印阈值，都会打印慢查询日志。 - 目前只支持强制开启打印慢查询日志，暂不支持通过 `WRITE_SLOW_LOG(FALSE)` 强制关闭打印慢查询日志。 @@ -188,7 +188,7 @@ 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-从-v900-版本开始引入)：用于定义慢查询日志的触发规则，支持多维度指标组合条件，以实现更加灵活和精细化的日志记录控制。该变量在 v9.0.0 版本中引入，逐步替代传统的单一阈值控制方式，即替代 `tidb_slow_log_threshold` 的使用。该变量支持将以下字段作为筛选条件，设置输出慢查询日志的条件。详情请参考[字段含义说明](#字段含义说明)。 +* [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-从-v856-版本开始引入)：用于定义慢查询日志的触发规则，支持多维度指标组合条件，以实现更加灵活和精细化的日志记录控制。该变量在 v8.5.6 版本中引入，逐步替代传统的单一阈值控制方式，即替代 `tidb_slow_log_threshold` 的使用。该变量支持将以下字段作为筛选条件，设置输出慢查询日志的条件。详情请参考[字段含义说明](#字段含义说明)。 - 支持的筛选字段： * Slow Query 基础信息： * `Query_time`、`Parse_time`、`Compile_time`、`Optimize_time`、`Wait_TS`、`Rewrite_time` @@ -253,7 +253,7 @@ SELECT /*+ WRITE_SLOW_LOG */ count(*) FROM t t1, t t2 WHERE t1.a = t2.b; > - `tidb_slow_log_rules` 用于替换单一阈值的方式，实现更灵活和精细化的慢查询日志控制，支持多维度指标组合条件。 > - 在资源充足的测试环境（1 个 TiDB 节点，16 核 CPU、48 GiB 内存；3 个 TiKV 节点，每个 16 核 CPU、48 GiB 内存）中，多次 sysbench 测试结果表明：当多维慢查询日志规则在 30 分钟内生成数百万条慢查询日志时，对性能影响较小；但当日志量达到千万级时，TPS 会明显下降，延迟也会显著增加。在业务负载较高或 CPU、内存资源接近瓶颈的情况下，应谨慎配置 `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-从-v900-版本开始引入)：用于设置每秒打印慢查询日志数量的上限，默认值为 `0`。 +* [`tidb_slow_log_max_per_sec`](/system-variables.md#tidb_slow_log_max_per_sec-从-v856-版本开始引入)：用于设置每秒打印慢查询日志数量的上限，默认值为 `0`。 * 当值为 `0` 时，表示不限制每秒打印的慢查询日志数量。 * 当值大于 `0` 时，TiDB 每秒最多打印指定数量的慢查询日志，超过部分将被丢弃，不会写入慢查询日志文件。 * 建议在启用了 `tidb_slow_log_rules` 后配置该变量，以防止基于规则的慢查询日志触发过于频繁。 diff --git a/system-variables.md b/system-variables.md index 6765625e4e2c..a90b7980adf3 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5062,7 +5062,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) > > 跳过字符检查可能会使 TiDB 检测不到应用写入的非法 UTF-8 字符，进一步导致执行 `ANALYZE` 时解码错误，以及引入其他未知的编码问题。如果应用不能保证写入字符串的合法性，不建议跳过该检查。 -### `tidb_slow_log_max_per_sec` 从 v9.0.0 版本开始引入 +### `tidb_slow_log_max_per_sec` 从 v8.5.6 版本开始引入 - 作用域：GLOBAL - 是否持久化到集群：是 @@ -5073,9 +5073,9 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) - 控制每个 TiDB 节点每秒打印的慢查询日志的数量上限。 - 当值为 `0` （默认值）时，表示不限制每秒打印的慢查询日志数量。 - 当值大于 `0` 时，TiDB 每秒最多打印指定数量的慢查询日志，超过部分将被丢弃，不会写入慢查询日志文件。 -- 该变量常与 [`tidb_slow_log_rules`](#tidb_slow_log_rules-从-v900-版本开始引入) 结合使用，以防止在高负载情况下产生过多的慢查询日志。 +- 该变量常与 [`tidb_slow_log_rules`](#tidb_slow_log_rules-从-v856-版本开始引入) 结合使用，以防止在高负载情况下产生过多的慢查询日志。 -### `tidb_slow_log_rules` 从 v9.0.0 版本开始引入 +### `tidb_slow_log_rules` 从 v8.5.6 版本开始引入 - 作用域：SESSION | GLOBAL - 是否持久化到集群：是 @@ -5086,7 +5086,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) > **Tip:** > -> 建议在启用 `tidb_slow_log_rules` 后，同时配置 [`tidb_slow_log_max_per_sec`](#tidb_slow_log_max_per_sec-从-v900-版本开始引入)，以限制慢查询日志打印频率，防止基于规则的慢查询日志触发过于频繁。 +> 建议在启用 `tidb_slow_log_rules` 后，同时配置 [`tidb_slow_log_max_per_sec`](#tidb_slow_log_max_per_sec-从-v856-版本开始引入)，以限制慢查询日志打印频率，防止基于规则的慢查询日志触发过于频繁。 ### `tidb_slow_log_threshold`