sys-var: clarify `tidb_slow_log_rules` syntax/behavior and de-duplicate slow log docs by zimulala · Pull Request #21337 · pingcap/docs-cn

zimulala · 2026-02-09T12:46:48Z

What is changed, added or deleted? (Required)

This PR refactors and clarifies tidb_slow_log_rules documentation in:

system-variables.md
identify-slow-queries.md

Main updates:

Reorganized tidb_slow_log_rules in system-variables.md with clearer structure:
- Unified syntax and constraints
- Type constraints
- Full field table (type/unit/summary)
- Effective behavior and matching order
- Examples and usage recommendations
Clarified key behavior/constraints:
- SESSION/GLOBAL rule capacity and separators
- SESSION does not support Conn_ID (GLOBAL only)
- Matching semantics (>= for numeric, = for string/bool)
- Rule update behavior (SET overwrites, not appends)
- Fallback to tidb_slow_log_threshold when no effective rules
- String values cannot contain , / ; (quoted values still not supported)
- Repeated fields in one rule: last value wins
- Time-unit distinction (tidb_slow_log_rules time fields are seconds, threshold is milliseconds)
Reduced duplication between docs:
- Kept rule contract/details in system-variables.md
- Added metric interpretation section in identify-slow-queries.md
- Replaced repeated long explanations with cross-references

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.

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

Fix issue: 完善 tidb_slow_log_rules 文档：字段/单位/取值范围（min-max）与语法约束 #21324
Other reference link(s): executor, variable: support cop_mvcc_read_amplification to trigger printing slow log tidb#66064

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

identify-slow-queries.md

system-variables.md

XuHuaiyu · 2026-02-10T08:22:04Z

system-variables.md

+- 规则更新行为：每次执行 `SET [SESSION|GLOBAL] tidb_slow_log_rules = '...'` 都会覆盖对应作用域原有规则，不会追加。
+- 规则清空行为：`SET [SESSION|GLOBAL] tidb_slow_log_rules = ''` 会清空对应作用域规则。
+- 在当前会话存在可生效的 `tidb_slow_log_rules`（SESSION 规则、GLOBAL 的当前 `Conn_ID` 规则，或未指定 `Conn_ID` 的全局规则）时，慢查询日志输出由规则匹配结果决定，`tidb_slow_log_threshold` 不再参与判断。
+- 在当前会话不存在可生效的规则（例如对应作用域规则被清空）时，慢查询日志触发仍依赖 `tidb_slow_log_threshold`（单位：毫秒）。


除了 对应作用域规则被清空 的情况，若所有规则均不生效，还会回退到使用 tidb_slow_log_threshold 进行判断吗

这里生效可能容易误解，我改一下哈。

XuHuaiyu · 2026-02-10T08:22:50Z

system-variables.md

+- 规则清空行为：`SET [SESSION|GLOBAL] tidb_slow_log_rules = ''` 会清空对应作用域规则。
+- 在当前会话存在可生效的 `tidb_slow_log_rules`（SESSION 规则、GLOBAL 的当前 `Conn_ID` 规则，或未指定 `Conn_ID` 的全局规则）时，慢查询日志输出由规则匹配结果决定，`tidb_slow_log_threshold` 不再参与判断。
+- 在当前会话不存在可生效的规则（例如对应作用域规则被清空）时，慢查询日志触发仍依赖 `tidb_slow_log_threshold`（单位：毫秒）。
+- 如果希望规则中仍使用 SQL 执行时间作为输出慢日志的条件，可在规则中使用 `Query_time`（单位：秒）并设置阈值。


这里再额外说明一下，注意 tidb_slow_log_threshold 单位是 ms，不要配错

上面 5224 行写了单位毫秒，感觉没必要特别说明了。

system-variables.md

ti-chi-bot · 2026-03-09T09:12:53Z

[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 hfxsd. 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.

Details

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 · 2026-03-09T09:13:08Z

PTAL @XuHuaiyu

identify-slow-queries.md

system-variables.md

ti-chi-bot · 2026-03-10T02:33:34Z

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

Details

In response to this:

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.

system-variables.md

Co-authored-by: xixirangrang <hfxsd@hotmail.com>

Add a new “tidb_slow_log_rules 使用方法” section to identify-slow-queries.md that documents rule syntax, type constraints, supported fields, matching semantics, scope/priority, examples and usage recommendations (including notes on units and rate-limiting). Remove the duplicated detailed rule text from system-variables.md and replace it with a link to the new section and an updated tip. This centralizes slow-log rule documentation on the slow-query diagnostics page and avoids maintaining the same content in multiple places.

Synced from: pingcap/docs-cn#21337 Target PR: pingcap#22567 AI Provider: gemini Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

identify-slow-queries.md

hfxsd · 2026-03-18T05:54:43Z

/retest

ti-chi-bot · 2026-03-20T03:25:45Z

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

Details

In response to this:

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.

*: update tidb_slow_log_rules

bb57032

ti-chi-bot bot added missing-translation-status This PR does not have translation status info. size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Feb 9, 2026

zimulala added the v9.0-beta.3 This PR/issue applies to TiDB v9.0-beta.3. label Feb 9, 2026

docs: fix markdownlint list spacing in tidb_slow_log_rules

77f26db

zimulala assigned yibin87 and XuHuaiyu Feb 10, 2026

XuHuaiyu reviewed Feb 10, 2026

View reviewed changes

hfxsd self-assigned this Mar 9, 2026

hfxsd added translation/doing This PR’s assignee is translating this PR. and removed missing-translation-status This PR does not have translation status info. labels Mar 9, 2026

zimulala commented Mar 9, 2026

View reviewed changes

system-variables.md Outdated Show resolved Hide resolved

hfxsd added the needs-cherry-pick-release-8.5 Should cherry pick this PR to release-8.5 branch. label Mar 9, 2026

hfxsd reviewed Mar 9, 2026

View reviewed changes

identify-slow-queries.md Outdated Show resolved Hide resolved

hfxsd reviewed Mar 9, 2026

View reviewed changes

system-variables.md Outdated Show resolved Hide resolved

XuHuaiyu approved these changes Mar 10, 2026

View reviewed changes

*: tiny update

403903b

zimulala force-pushed the docs/tidb_slow_log_rules-doc-improve-21324 branch from c652e99 to 403903b Compare March 10, 2026 06:58

hfxsd reviewed Mar 10, 2026

View reviewed changes

system-variables.md Outdated Show resolved Hide resolved

zimulala and others added 2 commits March 10, 2026 16:48

Update system-variables.md

689378e

Co-authored-by: xixirangrang <hfxsd@hotmail.com>

hfxsd changed the title ~~docs: clarify tidb_slow_log_rules syntax/behavior and de-duplicate slow log docs~~ sys-var: clarify tidb_slow_log_rules syntax/behavior and de-duplicate slow log docs Mar 13, 2026

hfxsd linked an issue Mar 13, 2026 that may be closed by this pull request

完善 tidb_slow_log_rules 文档：字段/单位/取值范围（min-max）与语法约束 #21324

Open

hfxsd reviewed Mar 18, 2026

View reviewed changes

identify-slow-queries.md Outdated Show resolved Hide resolved

Update identify-slow-queries.md

ebef6b6

hfxsd reviewed Mar 18, 2026

View reviewed changes

identify-slow-queries.md Outdated Show resolved Hide resolved

Update identify-slow-queries.md

840849c

hfxsd mentioned this pull request Mar 18, 2026

sys-var: clarify tidb_slow_log_rules syntax/behavior and de-duplicate slow log docs pingcap/docs#22567

Open

13 tasks

hfxsd added translation/done This PR has been translated from English into Chinese and updated to pingcap/docs-cn in a PR. and removed translation/doing This PR’s assignee is translating this PR. labels Mar 18, 2026

hfxsd requested a review from lilin90 March 19, 2026 07:21

hfxsd mentioned this pull request Mar 19, 2026

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

Closed

14 tasks

zhaoshangzi approved these changes Mar 20, 2026

View reviewed changes

Conversation

zimulala commented Feb 9, 2026 • edited by hfxsd Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

XuHuaiyu Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

zimulala Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

XuHuaiyu Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

zimulala Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ti-chi-bot bot commented Mar 9, 2026

Uh oh!

zimulala commented Mar 9, 2026

Uh oh!

Uh oh!

Uh oh!

ti-chi-bot bot commented Mar 10, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hfxsd commented Mar 18, 2026

Uh oh!

ti-chi-bot bot commented Mar 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

zimulala commented Feb 9, 2026 •

edited by hfxsd

Loading