docs: add a guide for configuring slow query trigger rules - #23767
docs: add a guide for configuring slow query trigger rules#23767qiancai wants to merge 15 commits into
Conversation
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
ti-chi-bot
Bot
added
missing-translation-status
qiancai
added
needs-cherry-pick-master
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Team Run ID: 📒 Files selected for processing (1)
Included review availability: Your plan provides up to 4 included reviews per hour; 0 remain after this review. 📝 WalkthroughWalkthroughAdds a dedicated guide for ChangesSlow Query Trigger Rules
Estimated code review effort: 2 (Simple) | ~10 minutes Merge Risk: 🟡 Moderate · up to The new guide may direct TiDB Cloud Starter users to configure an unsupported variable, and inconsistent numeric type terminology can make rule syntax unclear. Clarify platform availability and type definitions before merging. 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
ti-chi-bot
Bot
removed
the
missing-translation-status
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Team
Run ID: 25089249-19b3-42b5-a410-c5473dda5827
📒 Files selected for processing (7)
TOC-tidb-cloud-essential.mdTOC-tidb-cloud-premium.mdTOC.mdconfig-slow-query-trigger-rules.mdidentify-slow-queries.mdsystem-variables.mdtidb-cloud/tune-performance.md
💤 Files with no reviewable changes (1)
- identify-slow-queries.md
Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review.
There was a problem hiding this comment.
Actionable comments posted: 1
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Team
Run ID: cdefc522-d06b-4b69-acb2-220c9b2de355
📒 Files selected for processing (1)
config-slow-query-trigger-rules.md
Included review availability: Your plan provides up to 4 included reviews per hour; 1 remains after this review.
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
XuHuaiyu
left a comment
XuHuaiyu
left a comment
There was a problem hiding this comment.
P1 behavior-consistency findings from checking the documentation against TiDB release-8.5 code.
| For TiDB Self-Managed, the triggering behavior of slow query logs depends on the configuration of `tidb_slow_log_rules`: | ||
|
|
||
| - If `tidb_slow_log_rules` is not set, slow query log triggering still relies on [`tidb_slow_log_threshold`](/system-variables.md#tidb_slow_log_threshold) (in milliseconds). | ||
| - If `tidb_slow_log_rules` is set and the configured rules match the current session, the configured rules take precedence, and [`tidb_slow_log_threshold`](/system-variables.md#tidb_slow_log_threshold) will be ignored. |
There was a problem hiding this comment.
[P1] This wording conflates a rule being applicable to the current session with its conditions matching the current statement. The implementation switches away from tidb_slow_log_threshold whenever the session has any applicable rule (EffectiveFields is non-empty), even if no rule condition matches; it falls back to the threshold only when there are no applicable rules. Please align this summary with lines 172–173, for example: If the current session has any applicable rules, slow query log output is determined by the rule matching results, and tidb_slow_log_threshold is ignored. See https://github.com/pingcap/tidb/blob/ac41d7e3c8fcc7ffdb97311e2996cc9fb178e4c9/pkg/executor/adapter.go#L1785-L1795.
| - Numeric types (`int64`, `uint64`, `float64`) require values greater than or equal to `0`. Negative values result in a parsing error. | ||
| - `int64`: the maximum value is `2^63-1`. | ||
| - `uint64`: the maximum value is `2^64-1`. | ||
| - `float64`: the general upper limit is approximately `1.79e308`. Currently, parsing is done using Go's `ParseFloat`. While `NaN`/`Inf` can be parsed, they might lead to rules that are always true or always false. It is not recommended to use them. |
There was a problem hiding this comment.
[P1] This is the opposite of the release-8.5 implementation. Although strconv.ParseFloat accepts these spellings, parseFloat64 immediately rejects both NaN and any infinity with threshold value must be finite; the existing tests also assert those errors. Please document NaN, Inf, and -Inf as invalid values rather than values that are merely discouraged. See https://github.com/pingcap/tidb/blob/ac41d7e3c8fcc7ffdb97311e2996cc9fb178e4c9/pkg/sessionctx/variable/slow_log.go#L647-L658.
|
|
||
| ## Related system variables | ||
|
|
||
| * [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-new-in-v856): see [`tidb_slow_log_rules` recommendations](#recommendations) |
There was a problem hiding this comment.
[P1] This PR removes the Recommendations heading from this page, so the local #recommendations anchor is now broken. Please point it to the new page: /config-slow-query-trigger-rules.md#recommendations.
|
@zhaoshangzi: adding LGTM is restricted to approvers and reviewers in OWNERS files. DetailsIn 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. |
XuHuaiyu
left a comment
XuHuaiyu
left a comment
There was a problem hiding this comment.
P1 findings from re-reviewing this documentation against the current TiDB release-8.5 implementation.
| | `Resource_group` | `string` | none | The resource group that the statement is bound to. Matching is case-insensitive. | | ||
| | `KV_total` | `float` | second | The time spent on all the RPC requests to TiKV or TiFlash by this statement. | | ||
| | `PD_total` | `float` | second | The time spent on all the RPC requests to PD by this statement. | | ||
| | `Unpacked_bytes_sent_tikv_total` | `int` | bytes | The total amount of uncompressed data sent to TiKV by this statement. | |
There was a problem hiding this comment.
[P1] These eight Unpacked_bytes_* fields are not supported by the current release-8.5 implementation. The field registry does not contain them, so the parser rejects each one as an unknown slow-log field (registry, validation). The already-merged v8.5 backport, pingcap/tidb#66582, omitted these fields as well. Please remove all eight rows from the v8.5 docs, or land the corresponding release-8.5 code backport first.
|
|
||
| | Field name | Type | Unit | Description | | ||
| | --- | --- | --- | --- | | ||
| | `Conn_ID` | `uint` | count | The connection ID (session ID). For example, you can use `Conn_ID:3` to match logs whose session ID is `3`. This field is supported only in `GLOBAL` rules. | |
There was a problem hiding this comment.
[P1] Please document that Conn_ID is an exception to the general numeric >= matching rule. Global rules are indexed by the configured connection ID and TiDB only loads the entry for the current connection, so Conn_ID: 11 applies exactly to connection 11, not to every connection whose ID is at least 11 (selection logic).
| - This variable is often used with [`tidb_slow_log_rules`](#tidb_slow_log_rules) to prevent excessive slow query logs from being generated under high-workload conditions. | ||
|
|
||
| ### tidb_slow_log_rules <span class="version-mark">New in v8.5.6</span> | ||
| ### tidb_slow_log_rules <span class="version-mark">New in v8.5.6 and CLOUD.202603.1</span> {#tidb_slow_log_rule} |
There was a problem hiding this comment.
[P1] The explicit anchor is singular (tidb_slow_log_rule), but this PR links to #tidb_slow_log_rules throughout. This makes those links dead and is reported by the internal-links-anchors check. Please change the anchor to {#tidb_slow_log_rules}.
| </CustomContent> | ||
| <CustomContent platform="tidb-cloud"> | ||
|
|
||
| In the [TiDB Cloud console](/tidb-cloud/index.md), you can view slow queries on the [**Slow Query**](/tidb-cloud/tune-performance.md#slow-query) tab of the [**Diagnosis**](/tidb-cloud/tune-performance.md#view-the-diagnosis-page) page. |
There was a problem hiding this comment.
[P1] /tidb-cloud/index.md does not exist in this repository, so this link fails the internal-link and TOC checks. Please use the actual TiDB Cloud console URL (for example, https://tidbcloud.com/) or an existing docs page.
|
|
||
| In the [TiDB Cloud console](/tidb-cloud/index.md), you can view slow queries on the [**Slow Query**](/tidb-cloud/tune-performance.md#slow-query) tab of the [**Diagnosis**](/tidb-cloud/tune-performance.md#view-the-diagnosis-page) page. | ||
|
|
||
| By default, SQL queries that take more than 300 milliseconds are considered as slow queries. To configure the trigger rules for slow queries, you can modify the [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules) system variable. |
There was a problem hiding this comment.
[P1] This block targets all TiDB Cloud plans and therefore tells Starter users to modify tidb_slow_log_rules, while the system-variable entry in this PR explicitly says Starter does not support it. Please scope this variable-specific guidance to plan="dedicated,essential,premium" (or otherwise exclude Starter).
3 participants
What is changed, added or deleted? (Required)
Add a standalone guide for configuring slow query trigger rules so that users can find the supported fields, syntax constraints, matching behavior, and examples in one place.
The guide distinguishes the supported rule scopes and behavior for TiDB Self-Managed, TiDB Cloud Dedicated, and TiDB Cloud Essential/Premium. It also updates the related system variable documentation, TiDB Cloud performance guide, navigation entries, and 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)?
AI agent involvement
Do your changes match any of the following descriptions?
Summary by CodeRabbit