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

zimulala · 2025-10-17T07:46:22Z

First-time contributors' checklist

I've signed the Contributor License Agreement, which is required for the repository owners to accept my contribution.

What is changed, added or deleted? (Required)

pingcap/tidb#64010
Add slow log control variables (tidb_slow_log_rules, tidb_slow_log_max_per_sec) and hint write_slow_log

Which TiDB version(s) do your changes apply to? (Required)

Tips for choosing the affected version(s):

By default, CHOOSE MASTER ONLY so your changes will be applied to the next TiDB major or minor releases. If your PR involves a product feature behavior change or a compatibility change, CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER.

For details, see tips for choosing the affected versions (in Chinese).

What is the related PR or file link(s)?

This PR is translated from:
Other reference link(s):

Do your changes match any of the following descriptions?

Delete files
Change aliases
Need modification after applied to another branch
Might cause conflicts after applied to another branch

ti-chi-bot · 2025-10-22T09:29:02Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please ask for approval from lilin90. For more information see the Code Review Process.
Please ensure that each of them provides their approval before proceeding.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

zimulala · 2025-11-04T08:54:19Z

system-variables.md

+- 默认值：`0`
+- 类型：整数型
+- 范围：`[0, 1000000]`
+- 控制每秒打印慢日志每秒的次数上限，默认值 0。当该变量值为 0 时，则表示不限制每秒打印的慢日志数量。当该变量值大于 0 时，TiDB 会限制每秒打印的慢日志数量不超过该值，超过部分的慢日志将被丢弃，不会写入慢日志文件。该变量常与 [`tidb_slow_log_rules`](#tidb_slow_log_rules) 结合使用，以防止在高负载情况下产生过多的慢日志。


其中峰值可能超过配值（峰值 = 2*tidb_slow_log_max_per_sec），平均打印速率仍然受 tidb_slow_log_max_per_sec 限制。这个内容是否需要说明？

identify-slow-queries.md

yibin87 · 2025-11-19T08:30:55Z

identify-slow-queries.md

+* [tidb_slow_log_max_per_sec](/system-variables.md#tidb_slow_log_max_per_sec)：设置控制每秒打印慢日志的上限，默认值为 0。
+  * 当值为 0，其表示不限制每秒打印的慢日志数量。
+  * 当值大于 0 时，TiDB 每秒最多打印指定数量的慢日志，超过部分将被丢弃，不会写入慢日志文件。
+  * 建议在启用了 tidb_slow_log_rules 后配置该变量，以防规则触发频繁打印慢日志。


要不要再补充下，可能影响系统查询性能。

在下面几行的建议里面

identify-slow-queries.md

system-variables.md

yibin87

LGTM

ti-chi-bot · 2025-11-26T01:07:38Z

@yibin87: adding LGTM is restricted to approvers and reviewers in OWNERS files.

In response to this:

LGTM

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

zimulala · 2025-11-26T01:42:30Z

PTAL @lilin90

zimulala · 2025-12-01T11:09:28Z

PTAL @lilin90 @huoyao1125

lilin90

/bot-review

Copilot

Pull request overview

This PR adds documentation for new slow log control features in TiDB v9.0.0, including two system variables (tidb_slow_log_rules and tidb_slow_log_max_per_sec) and a new hint (WRITE_SLOW_LOG). These features provide more flexible and fine-grained control over slow query logging compared to the traditional single threshold approach.

Key Changes:

Introduced tidb_slow_log_rules variable to define multi-dimensional slow log trigger rules
Added tidb_slow_log_max_per_sec variable to rate-limit slow log output per TiDB instance
Documented the WRITE_SLOW_LOG hint to force slow log output regardless of thresholds

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
system-variables.md	Added documentation for two new system variables: `tidb_slow_log_rules` (SESSION/GLOBAL scope for defining trigger rules) and `tidb_slow_log_max_per_sec` (GLOBAL scope for rate limiting)
identify-slow-queries.md	Added documentation for the `WRITE_SLOW_LOG` hint and expanded the system variables section with detailed explanations of the new variables, including usage scenarios and interaction between rules and thresholds

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

identify-slow-queries.md

Copilot · 2025-12-04T10:06:03Z

identify-slow-queries.md

+  >
+  > 建议：在资源充足的测试环境（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，其表示不限制每秒打印的慢日志数量。


[nitpick] 建议修改措辞。"当值为 0，其表示不限制每秒打印的慢日志数量" 中的 "其" 字显得多余。建议改为："当值为 0 时，表示不限制每秒打印的慢日志数量。"

Suggested change

* 当值为 0，其表示不限制每秒打印的慢日志数量。

* 当值为 0 时，表示不限制每秒打印的慢日志数量。

Copilot · 2025-12-04T10:06:03Z

identify-slow-queries.md

+* [tidb_slow_log_max_per_sec](/system-variables.md#tidb_slow_log_max_per_sec)：设置控制每秒打印慢日志的上限，默认值为 0。
+    * 当值为 0，其表示不限制每秒打印的慢日志数量。
+    * 当值大于 0 时，TiDB 每秒最多打印指定数量的慢日志，超过部分将被丢弃，不会写入慢日志文件。
+    * 建议在启用了 tidb_slow_log_rules 后配置该变量，以防规则触发频繁打印慢日志。


[nitpick] 为了保持一致性，建议在文本中提及变量名称时使用反引号（backticks）包裹。例如，将 "tidb_slow_log_rules" 改为 "tidb_slow_log_rules"，将 "tidb_slow_log_threshold" 改为 "tidb_slow_log_threshold"，将 "tidb_slow_log_max_per_sec" 改为 "tidb_slow_log_max_per_sec"。这样可以与文档中其他地方的格式保持一致。

Suggested change

* 建议在启用了 tidb_slow_log_rules 后配置该变量，以防规则触发频繁打印慢日志。

* 建议在启用了 `tidb_slow_log_rules` 后配置该变量，以防规则触发频繁打印慢日志。

Copilot · 2025-12-04T10:06:04Z

identify-slow-queries.md

+  > 说明：`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。


[nitpick] 建议简化措辞。"设置控制每秒打印慢日志的上限" 中的 "设置" 和 "控制" 语义重复。建议改为："控制每秒打印慢日志的上限" 或 "设置每秒打印慢日志的上限"。

Suggested change

* [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。

Copilot · 2025-12-04T10:06:04Z

system-variables.md

+- 默认值：`0`
+- 类型：整数型
+- 范围：`[0, 1000000]`
+- 控制每个 TiDB 每秒打印慢日志的次数上限，默认值 0。当该变量值为 0 时，则表示不限制每个节点每秒打印的慢日志数量。当该变量值大于 0 时，会限制每个节点每秒打印的慢日志数量不超过该值，超过部分的慢日志将被丢弃，不会写入慢日志文件。该变量常与 [`tidb_slow_log_rules`](#tidb_slow_log_rules) 结合使用，以防止在高负载情况下产生过多的慢日志。


[nitpick] 建议简化措辞。"当该变量值为 0 时，则表示不限制..." 中的 "则" 字显得多余。建议改为："当该变量值为 0 时，表示不限制每个节点每秒打印的慢日志数量。"

Suggested change

- 控制每个 TiDB 每秒打印慢日志的次数上限，默认值 0。当该变量值为 0 时，则表示不限制每个节点每秒打印的慢日志数量。当该变量值大于 0 时，会限制每个节点每秒打印的慢日志数量不超过该值，超过部分的慢日志将被丢弃，不会写入慢日志文件。该变量常与 [`tidb_slow_log_rules`](#tidb_slow_log_rules) 结合使用，以防止在高负载情况下产生过多的慢日志。

- 控制每个 TiDB 每秒打印慢日志的次数上限，默认值 0。当该变量值为 0 时，表示不限制每个节点每秒打印的慢日志数量。当该变量值大于 0 时，会限制每个节点每秒打印的慢日志数量不超过该值，超过部分的慢日志将被丢弃，不会写入慢日志文件。该变量常与 [`tidb_slow_log_rules`](#tidb_slow_log_rules) 结合使用，以防止在高负载情况下产生过多的慢日志。

lilin90 · 2025-12-04T10:05:44Z

identify-slow-queries.md


-## 相关系统变量
+## 相关变量
+


Suggested change

本节介绍慢查询日志相关的 Hint 与系统变量。

lilin90 · 2025-12-04T10:07:48Z

identify-slow-queries.md

+
+### 相关 Hint
+
+通过 Hit `WRITE_SLOW_LOG` 强制控制输出慢日志。


Suggested change

通过 Hit `WRITE_SLOW_LOG` 强制控制输出慢日志。

你可以通过 Hint `WRITE_SLOW_LOG` 强制控制输出慢查询日志：

lilin90 · 2025-12-04T10:12:16Z

identify-slow-queries.md

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


Suggested change

- 不受任何阈值或触发规则限制，即无论该 SQL 是否达到慢日志打印阈值，都会打印慢日志。

- 暂不支持强制关闭打印慢日志的方式（如 `WRITE_SLOW_LOG(FALSE)`）。

- 该 Hint 不受任何阈值或触发规则限制，即无论该 SQL 查询是否达到慢查询日志打印阈值，都会打印慢查询日志。

- 目前只支持强制开启打印慢查询日志，暂不支持通过 `WRITE_SLOW_LOG(FALSE)` 强制关闭打印慢查询日志。

*: add two variables tidb_slow_log_rules and tidb_slow_log_max_per_sec

9d5d049

ti-chi-bot bot added missing-translation-status This PR does not have translation status info. size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Oct 17, 2025

qiancai added v9.0-beta.3 This PR/issue applies to TiDB v9.0-beta.3. translation/doing This PR’s assignee is translating this PR. and removed missing-translation-status This PR does not have translation status info. labels Oct 17, 2025

qiancai assigned lilin90 Oct 21, 2025

*: add WRITE_SLOW_LOG hint

a16078e

zimulala changed the title *: add two variables tidb_slow_log_rules and tidb_slow_log_max_per_sec *: add slow log control variables (tidb_slow_log_rules, tidb_slow_log_max_per_sec) and hint write_slow_log Oct 22, 2025

zimulala commented Nov 4, 2025

View reviewed changes

zimulala requested review from XuHuaiyu and yibin87 November 19, 2025 02:36

zimulala force-pushed the zimuxia/slow-log branch from 3552306 to a405cf8 Compare November 19, 2025 03:12

yibin87 reviewed Nov 19, 2025

View reviewed changes

*: add test info and tiny update

437be1b

zimulala force-pushed the zimuxia/slow-log branch from a405cf8 to 437be1b Compare November 19, 2025 08:41

zimulala added 2 commits November 20, 2025 16:43

*: address a comment

dd348f4

*: add version

f528b62

yibin87 approved these changes Nov 26, 2025

View reviewed changes

lilin90 reviewed Dec 4, 2025

View reviewed changes

lilin90 requested a review from Copilot December 4, 2025 10:02

Copilot started reviewing on behalf of lilin90 December 4, 2025 10:02 View session

Copilot finished reviewing on behalf of lilin90 December 4, 2025 10:04

Copilot AI reviewed Dec 4, 2025

View reviewed changes

Update format

25f85db

ti-chi-bot bot removed the size/M Denotes a PR that changes 30-99 lines, ignoring generated files. label Dec 4, 2025

ti-chi-bot bot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Dec 4, 2025

Refine wording and format

4c7c4ba

lilin90 reviewed Dec 4, 2025

View reviewed changes

	* 当值为 0，其表示不限制每秒打印的慢日志数量。
	* 当值为 0 时，表示不限制每秒打印的慢日志数量。

	* 建议在启用了 tidb_slow_log_rules 后配置该变量，以防规则触发频繁打印慢日志。
	* 建议在启用了 `tidb_slow_log_rules` 后配置该变量，以防规则触发频繁打印慢日志。

	* [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。



	本节介绍慢查询日志相关的 Hint 与系统变量。


		### 相关 Hint

		通过 Hit `WRITE_SLOW_LOG` 强制控制输出慢日志。

	通过 Hit `WRITE_SLOW_LOG` 强制控制输出慢日志。
	你可以通过 Hint `WRITE_SLOW_LOG` 强制控制输出慢查询日志：

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

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

Are you sure you want to change the base?

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

Uh oh!

Conversation

zimulala commented Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

First-time contributors' checklist

What is changed, added or deleted? (Required)

Which TiDB version(s) do your changes apply to? (Required)

What is the related PR or file link(s)?

Do your changes match any of the following descriptions?

Uh oh!

ti-chi-bot bot commented Oct 22, 2025

Uh oh!

zimulala Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

yibin87 Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

zimulala Nov 21, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

yibin87 left a comment

Choose a reason for hiding this comment

Uh oh!

ti-chi-bot bot commented Nov 26, 2025

Uh oh!

zimulala commented Nov 26, 2025

Uh oh!

zimulala commented Dec 1, 2025

Uh oh!

lilin90 left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

lilin90 Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

lilin90 Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

lilin90 Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

zimulala commented Oct 17, 2025 •

edited

Loading