From 13dbbe7195d96f18dfd76fe3301c4df588c0dee6 Mon Sep 17 00:00:00 2001 From: qiancai Date: Thu, 3 Sep 2026 17:55:42 +0800 Subject: [PATCH 01/18] move the info about slow query trigger rules to a separate doc --- TOC-tidb-cloud-essential.md | 1 + TOC-tidb-cloud-premium.md | 1 + TOC.md | 1 + define-slow-query-trigger-rules.md | 142 +++++++++++++++++++++++++++++ identify-slow-queries.md | 123 ------------------------- system-variables.md | 21 ++++- tidb-cloud/tune-performance.md | 8 ++ 7 files changed, 172 insertions(+), 125 deletions(-) create mode 100644 define-slow-query-trigger-rules.md diff --git a/TOC-tidb-cloud-essential.md b/TOC-tidb-cloud-essential.md index 697c30ab0ce5f..2115391850125 100644 --- a/TOC-tidb-cloud-essential.md +++ b/TOC-tidb-cloud-essential.md @@ -557,6 +557,7 @@ - [Server Status Variables](/status-variables.md) - [Table Filter](/table-filter.md) - [URI Formats of External Storage Services](/external-storage-uri.md) + - [Configure Trigger Rules for Slow Queries](/define-slow-query-trigger-rules.md) - [Troubleshoot Inconsistency Between Data and Indexes](/troubleshoot-data-inconsistency-errors.md) - [Notifications](/tidb-cloud/notifications.md) - [Project API Migration Guide for {{{ .starter }}} and Essential](/tidb-cloud/tidbx-starter-essential-project-api-migration-guide.md) diff --git a/TOC-tidb-cloud-premium.md b/TOC-tidb-cloud-premium.md index 4467337ad6a4f..8ed3fbe711bd6 100644 --- a/TOC-tidb-cloud-premium.md +++ b/TOC-tidb-cloud-premium.md @@ -479,6 +479,7 @@ - [Table Filter](/table-filter.md) - [URI Formats of External Storage Services](/external-storage-uri.md) - [`ANALYZE` Embedded in DDL Statements](/ddl_embedded_analyze.md) + - [Configure Trigger Rules for Slow Queries](/define-slow-query-trigger-rules.md) - [Troubleshoot Inconsistency Between Data and Indexes](/troubleshoot-data-inconsistency-errors.md) - [Notifications](/tidb-cloud/notifications.md) - Support Plan diff --git a/TOC.md b/TOC.md index 65231d45c782a..d7afb235545a8 100644 --- a/TOC.md +++ b/TOC.md @@ -213,6 +213,7 @@ - Issue Scenarios - Slow Queries - [Identify Slow Queries](/identify-slow-queries.md) + - [Configure Trigger Rules for Slow Queries](/define-slow-query-trigger-rules.md) - [Analyze Slow Queries](/analyze-slow-queries.md) - [TiDB OOM](/troubleshoot-tidb-oom.md) - [Hotspot](/troubleshoot-hot-spot-issues.md) diff --git a/define-slow-query-trigger-rules.md b/define-slow-query-trigger-rules.md new file mode 100644 index 0000000000000..150629f0abf85 --- /dev/null +++ b/define-slow-query-trigger-rules.md @@ -0,0 +1,142 @@ +--- +title: Configure Trigger Rules for Slow Queries +summary: Define the trigger rules for slow query logs. +--- + +# Configure Trigger Rules for Slow Queries + + + + +This document describes how to use [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-new-in-v856) to define the trigger rules for slow queries displayed in **Slow Query** page in the TiDB Cloud console. + +[`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-new-in-v856) supports multi-dimensional metric combinations. It is suitable for "targeted sampling" and "problem reproduction" of slow queries, enabling you to filter target statements based on specific metric combinations. + + + + + +This document describes how to use [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-new-in-v856) to define the trigger rules for slow query logs. + +[`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-new-in-v856) supports multi-dimensional metric combinations. It is suitable for "targeted sampling" and "problem reproduction" of slow query logs, enabling you to filter target statements based on specific metric combinations. + +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, the configured rules take precedence, and [`tidb_slow_log_threshold`](/system-variables.md#tidb_slow_log_threshold) will be ignored. + + + +For more information about meanings, diagnostic value, and background information of each field, see the [Fields description](#fields-description). + +## Unified rule syntax and type constraints + +- Rule capacity and separation: `SESSION` and `GLOBAL` each support a maximum of 10 rules. A single session can have up to 20 active rules. Rules are separated by `;`. +- Condition format: each condition uses the format `field_name:value`. Multiple conditions within a single rule are separated by `,`. +- Field and scope: field names are case-insensitive (underscores and other characters are preserved). `SESSION` rules do not support `Conn_ID`. Only `GLOBAL` rules support `Conn_ID`. +- Matching semantics: + - Numeric fields are matched using `>=`. String and boolean fields are matched using equality (`=`). + - Matching for `DB` and `Resource_group` is case-insensitive. + - Explicit operators such as `>`, `<`, and `!=` are not supported. + +Type constraints are as follows: + +- Numeric types (`int64`, `uint64`, `float64`) uniformly require `>= 0`. Negative values will 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. +- `bool`: supports `true`/`false`, `1`/`0`, and `t`/`f` (case-insensitive). +- `string`: currently does not support strings containing the separators `,` (condition separator) or `;` (rule separator), even with quotes (single or double). Escaping is not supported. +- Duplicate fields: if the same field is specified multiple times in a single rule, the last occurrence takes effect. + +## Supported fields + +For detailed field descriptions, diagnostic meanings, and background information, see the [field descriptions in `identify-slow-queries`](/identify-slow-queries.md#fields-description). + +Unless otherwise noted, the fields in the following table follow the general matching and type rules described in [Unified rule syntax and type constraints](#unified-rule-syntax-and-type-constraints). This table lists only the currently supported field names, types, units, and a few rule-specific notes. It does not repeat each field's semantic meaning. + +| Field name | Type | Unit | Notes | +| -------------------------------------- | -------- | ------ | ------------------------------ | +| `Conn_ID` | `uint` | count | Supported only in `GLOBAL` rules | +| `Session_alias` | `string` | none | - | +| `DB` | `string` | none | Case-insensitive when matched | +| `Exec_retry_count` | `uint` | count | - | +| `Query_time` | `float` | second | - | +| `Parse_time` | `float` | second | - | +| `Compile_time` | `float` | second | - | +| `Rewrite_time` | `float` | second | - | +| `Optimize_time` | `float` | second | - | +| `Wait_TS` | `float` | second | - | +| `Is_internal` | `bool` | none | - | +| `Digest` | `string` | none | - | +| `Plan_digest` | `string` | none | - | +| `Num_cop_tasks` | `int` | count | - | +| `Mem_max` | `int` | bytes | - | +| `Disk_max` | `int` | bytes | - | +| `Write_sql_response_total` | `float` | second | - | +| `Succ` | `bool` | none | - | +| `Resource_group` | `string` | none | Case-insensitive when matched | +| `KV_total` | `float` | second | - | +| `PD_total` | `float` | second | - | +| `Unpacked_bytes_sent_tikv_total` | `int` | bytes | - | +| `Unpacked_bytes_received_tikv_total` | `int` | bytes | - | +| `Unpacked_bytes_sent_tikv_cross_zone` | `int` | bytes | - | +| `Unpacked_bytes_received_tikv_cross_zone` | `int` | bytes | - | +| `Unpacked_bytes_sent_tiflash_total` | `int` | bytes | - | +| `Unpacked_bytes_received_tiflash_total` | `int` | bytes | - | +| `Unpacked_bytes_sent_tiflash_cross_zone` | `int` | bytes | - | +| `Unpacked_bytes_received_tiflash_cross_zone` | `int` | bytes | - | +| `Process_time` | `float` | second | - | +| `Backoff_time` | `float` | second | - | +| `Total_keys` | `uint` | count | - | +| `Process_keys` | `uint` | count | - | +| `cop_mvcc_read_amplification` | `float` | ratio | Ratio value (`Total_keys / Process_keys`) | +| `Prewrite_time` | `float` | second | - | +| `Commit_time` | `float` | second | - | +| `Write_keys` | `uint` | count | - | +| `Write_size` | `uint` | bytes | - | +| `Prewrite_region` | `uint` | count | - | + +## Effective behavior and matching order + +- Rule update behavior: every execution of `SET [SESSION|GLOBAL] tidb_slow_log_rules = '...'` overwrites the existing rules in that scope instead of appending to them. +- Rule clearing behavior: `SET [SESSION|GLOBAL] tidb_slow_log_rules = ''` clears the rules in the corresponding scope. +- If the current session has any applicable `tidb_slow_log_rules`, such as `SESSION` rules, `GLOBAL` rules for the current `Conn_ID`, or generic global rules without `Conn_ID`, the output of slow query logs is determined by rule matching results, and `tidb_slow_log_threshold` is no longer used. +- If the current session has no applicable rules, for example when both `SESSION` and `GLOBAL` rules are empty, or only `GLOBAL` rules that do not match the current `Conn_ID` are configured, slow query logging still depends on `tidb_slow_log_threshold`. Note that the unit is milliseconds. +- If you still want to use SQL execution time as a condition for writing slow query logs, use `Query_time` in the rule and note that the unit is seconds. +- Rule matching logic: + - Multiple rules are combined with `OR`, while multiple field conditions within a single rule are combined with `AND`. + - `SESSION`-scope rules are matched first. If none matches, TiDB then matches `GLOBAL` rules for the current `Conn_ID`, followed by generic `GLOBAL` rules without `Conn_ID`. +- `SHOW VARIABLES LIKE 'tidb_slow_log_rules'` and `SELECT @@SESSION.tidb_slow_log_rules` return the `SESSION` rule text, or an empty string if unset. `SELECT @@GLOBAL.tidb_slow_log_rules` returns the `GLOBAL` rule text. + +## Examples + +- Standard format (`SESSION` scope): + + ```sql + SET SESSION tidb_slow_log_rules = 'Query_time: 0.5, Is_internal: false'; + ``` + +- Invalid format (`SESSION` scope does not support `Conn_ID`): + + ```sql + SET SESSION tidb_slow_log_rules = 'Conn_ID: 12, Query_time: 0.5, Is_internal: false'; + ``` + +- Global rule (applies to all connections): + + ```sql + SET GLOBAL tidb_slow_log_rules = 'Query_time: 0.5, Is_internal: false'; + ``` + +- Global rules for specific connections (applied separately to the two connections `Conn_ID:11` and `Conn_ID:12`): + + ```sql + SET GLOBAL tidb_slow_log_rules = 'Conn_ID: 11, Query_time: 0.5, Is_internal: false; Conn_ID: 12, Query_time: 0.6, Process_time: 0.3, DB: db1'; + ``` + +## Recommendations + +- `tidb_slow_log_rules` is designed to replace the single-threshold approach. It supports combinations of multi-dimensional metric conditions, enabling more flexible and fine-grained control over slow query logging. + +- In a well-provisioned test environment with 1 TiDB node (16 CPU cores, 48 GiB memory) and 3 TiKV nodes (each with 16 CPU cores and 48 GiB memory), repeated sysbench tests show that performance impact remains small when multi-dimensional slow query log rules generate millions of slow log entries within 30 minutes. However, when the log volume reaches tens of millions, TPS drops significantly and latency increases noticeably. Therefore, if business workload is high or CPU and memory resources are close to their limits, configure `tidb_slow_log_rules` carefully to avoid log flooding caused by overly broad rules. If you need to limit the log output rate, use [`tidb_slow_log_max_per_sec`](/system-variables.md#tidb_slow_log_max_per_sec-new-in-v856) to throttle it and reduce the impact on business performance. \ No newline at end of file diff --git a/identify-slow-queries.md b/identify-slow-queries.md index e84fb959e1e5f..bf3c45545064f 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -172,129 +172,6 @@ Fields related to storage engines: - `Storage_from_kv`: introduced in v8.5.5, indicates whether this statement read data from TiKV. - `Storage_from_mpp`: introduced in v8.5.5, indicates whether this statement read data from TiFlash. -## Use `tidb_slow_log_rules` - -[`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-new-in-v856) is used to define trigger rules for slow query logs, supporting multi-dimensional metric combinations. It is suitable for "targeted sampling" and "problem reproduction" of slow logs, enabling you to filter target statements based on specific metric combinations. - -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, the configured rules take precedence, and [`tidb_slow_log_threshold`](/system-variables.md#tidb_slow_log_threshold) will be ignored. - -For more information about meanings, diagnostic value, and background information of each field, see the [Fields description](#fields-description). - -### Unified rule syntax and type constraints - -- Rule capacity and separation: `SESSION` and `GLOBAL` each support a maximum of 10 rules. A single session can have up to 20 active rules. Rules are separated by `;`. -- Condition format: each condition uses the format `field_name:value`. Multiple conditions within a single rule are separated by `,`. -- Field and scope: field names are case-insensitive (underscores and other characters are preserved). `SESSION` rules do not support `Conn_ID`. Only `GLOBAL` rules support `Conn_ID`. -- Matching semantics: - - Numeric fields are matched using `>=`. String and boolean fields are matched using equality (`=`). - - Matching for `DB` and `Resource_group` is case-insensitive. - - Explicit operators such as `>`, `<`, and `!=` are not supported. - -Type constraints are as follows: - -- Numeric types (`int64`, `uint64`, `float64`) uniformly require `>= 0`. Negative values will 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. -- `bool`: supports `true`/`false`, `1`/`0`, and `t`/`f` (case-insensitive). -- `string`: currently does not support strings containing the separators `,` (condition separator) or `;` (rule separator), even with quotes (single or double). Escaping is not supported. -- Duplicate fields: if the same field is specified multiple times in a single rule, the last occurrence takes effect. - -### Supported fields - -For detailed field descriptions, diagnostic meanings, and background information, see the [field descriptions in `identify-slow-queries`](/identify-slow-queries.md#fields-description). - -Unless otherwise noted, the fields in the following table follow the general matching and type rules described in [Unified rule syntax and type constraints](#unified-rule-syntax-and-type-constraints). This table lists only the currently supported field names, types, units, and a few rule-specific notes. It does not repeat each field's semantic meaning. - -| Field name | Type | Unit | Notes | -| -------------------------------------- | -------- | ------ | ------------------------------ | -| `Conn_ID` | `uint` | count | Supported only in `GLOBAL` rules | -| `Session_alias` | `string` | none | - | -| `DB` | `string` | none | Case-insensitive when matched | -| `Exec_retry_count` | `uint` | count | - | -| `Query_time` | `float` | second | - | -| `Parse_time` | `float` | second | - | -| `Compile_time` | `float` | second | - | -| `Rewrite_time` | `float` | second | - | -| `Optimize_time` | `float` | second | - | -| `Wait_TS` | `float` | second | - | -| `Is_internal` | `bool` | none | - | -| `Digest` | `string` | none | - | -| `Plan_digest` | `string` | none | - | -| `Num_cop_tasks` | `int` | count | - | -| `Mem_max` | `int` | bytes | - | -| `Disk_max` | `int` | bytes | - | -| `Write_sql_response_total` | `float` | second | - | -| `Succ` | `bool` | none | - | -| `Resource_group` | `string` | none | Case-insensitive when matched | -| `KV_total` | `float` | second | - | -| `PD_total` | `float` | second | - | -| `Unpacked_bytes_sent_tikv_total` | `int` | bytes | - | -| `Unpacked_bytes_received_tikv_total` | `int` | bytes | - | -| `Unpacked_bytes_sent_tikv_cross_zone` | `int` | bytes | - | -| `Unpacked_bytes_received_tikv_cross_zone` | `int` | bytes | - | -| `Unpacked_bytes_sent_tiflash_total` | `int` | bytes | - | -| `Unpacked_bytes_received_tiflash_total` | `int` | bytes | - | -| `Unpacked_bytes_sent_tiflash_cross_zone` | `int` | bytes | - | -| `Unpacked_bytes_received_tiflash_cross_zone` | `int` | bytes | - | -| `Process_time` | `float` | second | - | -| `Backoff_time` | `float` | second | - | -| `Total_keys` | `uint` | count | - | -| `Process_keys` | `uint` | count | - | -| `cop_mvcc_read_amplification` | `float` | ratio | Ratio value (`Total_keys / Process_keys`) | -| `Prewrite_time` | `float` | second | - | -| `Commit_time` | `float` | second | - | -| `Write_keys` | `uint` | count | - | -| `Write_size` | `uint` | bytes | - | -| `Prewrite_region` | `uint` | count | - | - -### Effective behavior and matching order - -- Rule update behavior: every execution of `SET [SESSION|GLOBAL] tidb_slow_log_rules = '...'` overwrites the existing rules in that scope instead of appending to them. -- Rule clearing behavior: `SET [SESSION|GLOBAL] tidb_slow_log_rules = ''` clears the rules in the corresponding scope. -- If the current session has any applicable `tidb_slow_log_rules`, such as `SESSION` rules, `GLOBAL` rules for the current `Conn_ID`, or generic global rules without `Conn_ID`, the output of slow query logs is determined by rule matching results, and `tidb_slow_log_threshold` is no longer used. -- If the current session has no applicable rules, for example when both `SESSION` and `GLOBAL` rules are empty, or only `GLOBAL` rules that do not match the current `Conn_ID` are configured, slow query logging still depends on `tidb_slow_log_threshold`. Note that the unit is milliseconds. -- If you still want to use SQL execution time as a condition for writing slow logs, use `Query_time` in the rule and note that the unit is seconds. -- Rule matching logic: - - Multiple rules are combined with `OR`, while multiple field conditions within a single rule are combined with `AND`. - - `SESSION`-scope rules are matched first. If none matches, TiDB then matches `GLOBAL` rules for the current `Conn_ID`, followed by generic `GLOBAL` rules without `Conn_ID`. -- `SHOW VARIABLES LIKE 'tidb_slow_log_rules'` and `SELECT @@SESSION.tidb_slow_log_rules` return the `SESSION` rule text, or an empty string if unset. `SELECT @@GLOBAL.tidb_slow_log_rules` returns the `GLOBAL` rule text. - -### Examples - -- Standard format (`SESSION` scope): - - ```sql - SET SESSION tidb_slow_log_rules = 'Query_time: 0.5, Is_internal: false'; - ``` - -- Invalid format (`SESSION` scope does not support `Conn_ID`): - - ```sql - SET SESSION tidb_slow_log_rules = 'Conn_ID: 12, Query_time: 0.5, Is_internal: false'; - ``` - -- Global rule (applies to all connections): - - ```sql - SET GLOBAL tidb_slow_log_rules = 'Query_time: 0.5, Is_internal: false'; - ``` - -- Global rules for specific connections (applied separately to the two connections `Conn_ID:11` and `Conn_ID:12`): - - ```sql - SET GLOBAL tidb_slow_log_rules = 'Conn_ID: 11, Query_time: 0.5, Is_internal: false; Conn_ID: 12, Query_time: 0.6, Process_time: 0.3, DB: db1'; - ``` - -### Recommendations - -- `tidb_slow_log_rules` is designed to replace the single-threshold approach. It supports combinations of multi-dimensional metric conditions, enabling more flexible and fine-grained control over slow query logging. - -- In a well-provisioned test environment with 1 TiDB node (16 CPU cores, 48 GiB memory) and 3 TiKV nodes (each with 16 CPU cores and 48 GiB memory), repeated sysbench tests show that performance impact remains small when multi-dimensional slow query log rules generate millions of slow log entries within 30 minutes. However, when the log volume reaches tens of millions, TPS drops significantly and latency increases noticeably. Therefore, if business workload is high or CPU and memory resources are close to their limits, configure `tidb_slow_log_rules` carefully to avoid log flooding caused by overly broad rules. If you need to limit the log output rate, use [`tidb_slow_log_max_per_sec`](/system-variables.md#tidb_slow_log_max_per_sec-new-in-v856) to throttle it and reduce the impact on business performance. - ## Related system variables * [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-new-in-v856): see [`tidb_slow_log_rules` recommendations](#recommendations) diff --git a/system-variables.md b/system-variables.md index c738522eb18b2..818098f05e9d7 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5981,9 +5981,15 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) - A value greater than `0` means TiDB writes at most the specified number of slow query log entries per second. Any excess log entries are discarded and not written to the slow query log file. - This variable is often used with [`tidb_slow_log_rules`](#tidb_slow_log_rules-new-in-v856) to prevent excessive slow query logs from being generated under high-workload conditions. -### tidb_slow_log_rules New in v8.5.6 +### tidb_slow_log_rules New in v8.5.6 and TiDB-X-CLOUD.202603 -- Scope: SESSION | GLOBAL +>**Note:** +> +> This variable is not supported on TiDB Cloud Starter. + +- Scope + - TiDB Self-Managed and TiDB Cloud Dedicated: SESSION | GLOBAL + - TiDB Cloud Essential and Premium: SESSION - Persists to cluster: Yes - Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No - Default value: "" @@ -5991,11 +5997,22 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) - This variable defines the triggering rules for slow query logs. It supports combining multi-dimensional metrics to provide more flexible and fine-grained logging. - For more information about how to use this system variable, see [Use `tidb_slow_log_rules`](/identify-slow-queries.md#use-tidb_slow_log_rules). + + > **Tip:** > > - When enabling `tidb_slow_log_rules` in a production environment, it is recommended to also configure [`tidb_slow_log_max_per_sec`](#tidb_slow_log_max_per_sec-new-in-v856) to avoid excessively frequent slow query log printing. > - It is recommended to start with stricter conditions and gradually relax them based on troubleshooting needs. For more information on performance impact, see [Recommendations](/identify-slow-queries.md#recommendations). + + + +> **Tip:** +> +> It is recommended to start with stricter conditions and gradually relax them based on troubleshooting needs. For more information on performance impact, see [Recommendations](/identify-slow-queries.md#recommendations). + + + ### tidb_slow_log_threshold > **Note:** diff --git a/tidb-cloud/tune-performance.md b/tidb-cloud/tune-performance.md index 8c07de956eb46..b7ba8d9e9f86d 100644 --- a/tidb-cloud/tune-performance.md +++ b/tidb-cloud/tune-performance.md @@ -46,6 +46,14 @@ TiDB Cloud provides [Slow Query](#slow-query) and [Statement Analysis](#statemen By default, SQL queries that take more than 300 milliseconds are considered as slow queries. + + +> **Note:** +> +> You can also configure trigger rules for slow queries to filter target statements based on specific metric combinations. For more information, see [Configure Trigger Rules for Slow Queries](/define-slow-query-trigger-rules.md). + + + To view slow queries in a {{{ .starter }}} instance{{{ .essential }}} instance{{{ .premium }}} instance{{{ .dedicated }}} cluster, perform the following steps: 1. [Navigate to the **Diagnosis** page](#view-the-diagnosis-page). From 85189fca1ea04afc0b9f00925b4285c8f83e4c0c Mon Sep 17 00:00:00 2001 From: qiancai Date: Thu, 3 Sep 2026 18:47:25 +0800 Subject: [PATCH 02/18] Update define-slow-query-trigger-rules.md --- define-slow-query-trigger-rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/define-slow-query-trigger-rules.md b/define-slow-query-trigger-rules.md index 150629f0abf85..a38c89be6a727 100644 --- a/define-slow-query-trigger-rules.md +++ b/define-slow-query-trigger-rules.md @@ -8,7 +8,7 @@ summary: Define the trigger rules for slow query logs. -This document describes how to use [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-new-in-v856) to define the trigger rules for slow queries displayed in **Slow Query** page in the TiDB Cloud console. +This document describes how to use [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-new-in-v856) to define the trigger rules for slow queries displayed in [**Slow Query**](/tidb-cloud/tune-performance.md#slow-query) page in the TiDB Cloud console. [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-new-in-v856) supports multi-dimensional metric combinations. It is suitable for "targeted sampling" and "problem reproduction" of slow queries, enabling you to filter target statements based on specific metric combinations. From 8b92cd386ea82ba4befbb8f6cd4db7b8003f162a Mon Sep 17 00:00:00 2001 From: qiancai Date: Fri, 4 Sep 2026 15:49:18 +0800 Subject: [PATCH 03/18] add field descriptions --- define-slow-query-trigger-rules.md | 93 ++++++++++++++---------------- 1 file changed, 44 insertions(+), 49 deletions(-) diff --git a/define-slow-query-trigger-rules.md b/define-slow-query-trigger-rules.md index a38c89be6a727..d0db507629ee2 100644 --- a/define-slow-query-trigger-rules.md +++ b/define-slow-query-trigger-rules.md @@ -5,7 +5,6 @@ summary: Define the trigger rules for slow query logs. # Configure Trigger Rules for Slow Queries - This document describes how to use [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-new-in-v856) to define the trigger rules for slow queries displayed in [**Slow Query**](/tidb-cloud/tune-performance.md#slow-query) page in the TiDB Cloud console. @@ -27,8 +26,6 @@ For TiDB Self-Managed, the triggering behavior of slow query logs depends on the -For more information about meanings, diagnostic value, and background information of each field, see the [Fields description](#fields-description). - ## Unified rule syntax and type constraints - Rule capacity and separation: `SESSION` and `GLOBAL` each support a maximum of 10 rules. A single session can have up to 20 active rules. Rules are separated by `;`. @@ -51,51 +48,49 @@ Type constraints are as follows: ## Supported fields -For detailed field descriptions, diagnostic meanings, and background information, see the [field descriptions in `identify-slow-queries`](/identify-slow-queries.md#fields-description). - -Unless otherwise noted, the fields in the following table follow the general matching and type rules described in [Unified rule syntax and type constraints](#unified-rule-syntax-and-type-constraints). This table lists only the currently supported field names, types, units, and a few rule-specific notes. It does not repeat each field's semantic meaning. - -| Field name | Type | Unit | Notes | -| -------------------------------------- | -------- | ------ | ------------------------------ | -| `Conn_ID` | `uint` | count | Supported only in `GLOBAL` rules | -| `Session_alias` | `string` | none | - | -| `DB` | `string` | none | Case-insensitive when matched | -| `Exec_retry_count` | `uint` | count | - | -| `Query_time` | `float` | second | - | -| `Parse_time` | `float` | second | - | -| `Compile_time` | `float` | second | - | -| `Rewrite_time` | `float` | second | - | -| `Optimize_time` | `float` | second | - | -| `Wait_TS` | `float` | second | - | -| `Is_internal` | `bool` | none | - | -| `Digest` | `string` | none | - | -| `Plan_digest` | `string` | none | - | -| `Num_cop_tasks` | `int` | count | - | -| `Mem_max` | `int` | bytes | - | -| `Disk_max` | `int` | bytes | - | -| `Write_sql_response_total` | `float` | second | - | -| `Succ` | `bool` | none | - | -| `Resource_group` | `string` | none | Case-insensitive when matched | -| `KV_total` | `float` | second | - | -| `PD_total` | `float` | second | - | -| `Unpacked_bytes_sent_tikv_total` | `int` | bytes | - | -| `Unpacked_bytes_received_tikv_total` | `int` | bytes | - | -| `Unpacked_bytes_sent_tikv_cross_zone` | `int` | bytes | - | -| `Unpacked_bytes_received_tikv_cross_zone` | `int` | bytes | - | -| `Unpacked_bytes_sent_tiflash_total` | `int` | bytes | - | -| `Unpacked_bytes_received_tiflash_total` | `int` | bytes | - | -| `Unpacked_bytes_sent_tiflash_cross_zone` | `int` | bytes | - | -| `Unpacked_bytes_received_tiflash_cross_zone` | `int` | bytes | - | -| `Process_time` | `float` | second | - | -| `Backoff_time` | `float` | second | - | -| `Total_keys` | `uint` | count | - | -| `Process_keys` | `uint` | count | - | -| `cop_mvcc_read_amplification` | `float` | ratio | Ratio value (`Total_keys / Process_keys`) | -| `Prewrite_time` | `float` | second | - | -| `Commit_time` | `float` | second | - | -| `Write_keys` | `uint` | count | - | -| `Write_size` | `uint` | bytes | - | -| `Prewrite_region` | `uint` | count | - | +The fields in the following table follow the general matching and type rules described in [Unified rule syntax and type constraints](#unified-rule-syntax-and-type-constraints), unless otherwise noted. + +| 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. | +| `Session_alias` | `string` | none | The alias of the current session. | +| `DB` | `string` | none | The current database. Matching is case-insensitive. | +| `Exec_retry_count` | `uint` | count | The retry times of this statement. This field is usually for pessimistic transactions in which the statement is retried when the lock fails. | +| `Query_time` | `float` | second | The execution time of a statement. | +| `Parse_time` | `float` | second | The parsing time for the statement. | +| `Compile_time` | `float` | second | The duration of the query optimization. | +| `Rewrite_time` | `float` | second | The time consumed for rewriting the query of this statement. | +| `Optimize_time` | `float` | second | The time consumed for optimizing the execution plan. | +| `Wait_TS` | `float` | second | The waiting time of the statement to get transaction timestamps. | +| `Is_internal` | `bool` | none | Whether a SQL statement is internal to TiDB. `true` indicates that the statement is executed internally in TiDB, and `false` indicates that the statement is executed by the user. | +| `Digest` | `string` | none | The fingerprint of the SQL statement. | +| `Plan_digest` | `string` | none | The digest of the execution plan. | +| `Num_cop_tasks` | `int` | count | The number of Coprocessor tasks sent by this statement. | +| `Mem_max` | `int` | bytes | The maximum memory space used during the execution period of a SQL statement. | +| `Disk_max` | `int` | bytes | The maximum disk space used during the execution period of a SQL statement. | +| `Write_sql_response_total` | `float` | second | The time consumed for sending the results back to the client by this statement. | +| `Succ` | `bool` | none | Whether a statement is executed successfully. | +| `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. | +| `Unpacked_bytes_received_tikv_total` | `int` | bytes | The total amount of uncompressed data received from TiKV by this statement. | +| `Unpacked_bytes_sent_tikv_cross_zone` | `int` | bytes | The amount of uncompressed data sent to TiKV across availability zones by this statement. | +| `Unpacked_bytes_received_tikv_cross_zone` | `int` | bytes | The amount of uncompressed data received from TiKV across availability zones by this statement. | +| `Unpacked_bytes_sent_tiflash_total` | `int` | bytes | The total amount of uncompressed data sent to TiFlash by this statement. | +| `Unpacked_bytes_received_tiflash_total` | `int` | bytes | The total amount of uncompressed data received from TiFlash by this statement. | +| `Unpacked_bytes_sent_tiflash_cross_zone` | `int` | bytes | The amount of uncompressed data sent to TiFlash across availability zones by this statement. | +| `Unpacked_bytes_received_tiflash_cross_zone` | `int` | bytes | The amount of uncompressed data received from TiFlash across availability zones by this statement. | +| `Process_time` | `float` | second | The total processing time of a SQL statement in TiKV. Because data is sent to TiKV concurrently, this value might exceed `Query_time`. | +| `Backoff_time` | `float` | second | The waiting time before retrying when a statement encounters errors that require a retry. Common errors include lock conflicts, Region splits, and busy TiKV servers. | +| `Total_keys` | `uint` | count | The number of keys that Coprocessor has scanned. | +| `Process_keys` | `uint` | count | The number of keys that Coprocessor has processed. Compared with `Total_keys`, `Process_keys` does not include old versions of MVCC. A large difference between `Process_keys` and `Total_keys` indicates that many old versions exist. | +| `cop_mvcc_read_amplification` | `float` | ratio | The MVCC read amplification ratio, calculated as `Total_keys / Process_keys`. | +| `Prewrite_time` | `float` | second | The duration of the first phase (prewrite) of the two-phase transaction commit. | +| `Commit_time` | `float` | second | The duration of the second phase (commit) of the two-phase transaction commit. | +| `Write_keys` | `uint` | count | The count of keys that the transaction writes to the Write CF in TiKV. | +| `Write_size` | `uint` | bytes | The total size of the keys or values to be written when the transaction commits. | +| `Prewrite_region` | `uint` | count | The number of TiKV Regions involved in the first phase (prewrite) of the two-phase transaction commit. Each Region triggers a remote procedure call. | ## Effective behavior and matching order @@ -139,4 +134,4 @@ Unless otherwise noted, the fields in the following table follow the general mat - `tidb_slow_log_rules` is designed to replace the single-threshold approach. It supports combinations of multi-dimensional metric conditions, enabling more flexible and fine-grained control over slow query logging. -- In a well-provisioned test environment with 1 TiDB node (16 CPU cores, 48 GiB memory) and 3 TiKV nodes (each with 16 CPU cores and 48 GiB memory), repeated sysbench tests show that performance impact remains small when multi-dimensional slow query log rules generate millions of slow log entries within 30 minutes. However, when the log volume reaches tens of millions, TPS drops significantly and latency increases noticeably. Therefore, if business workload is high or CPU and memory resources are close to their limits, configure `tidb_slow_log_rules` carefully to avoid log flooding caused by overly broad rules. If you need to limit the log output rate, use [`tidb_slow_log_max_per_sec`](/system-variables.md#tidb_slow_log_max_per_sec-new-in-v856) to throttle it and reduce the impact on business performance. \ No newline at end of file +- In a well-provisioned test environment with 1 TiDB node (16 CPU cores, 48 GiB memory) and 3 TiKV nodes (each with 16 CPU cores and 48 GiB memory), repeated sysbench tests show that performance impact remains small when multi-dimensional slow query log rules generate millions of slow log entries within 30 minutes. However, when the log volume reaches tens of millions, TPS drops significantly and latency increases noticeably. Therefore, if business workload is high or CPU and memory resources are close to their limits, configure `tidb_slow_log_rules` carefully to avoid log flooding caused by overly broad rules. If you need to limit the log output rate, use [`tidb_slow_log_max_per_sec`](/system-variables.md#tidb_slow_log_max_per_sec-new-in-v856) to throttle it and reduce the impact on business performance. From 4f5dfa3a550e43d8999217d02c2275d9daaa2fcd Mon Sep 17 00:00:00 2001 From: qiancai Date: Fri, 4 Sep 2026 17:17:41 +0800 Subject: [PATCH 04/18] rename the docs for slow-query-trigger-rules --- ...s.md => config-slow-query-trigger-rules.md | 31 ++++++++++++++----- system-variables.md | 2 +- 2 files changed, 24 insertions(+), 9 deletions(-) rename define-slow-query-trigger-rules.md => config-slow-query-trigger-rules.md (90%) diff --git a/define-slow-query-trigger-rules.md b/config-slow-query-trigger-rules.md similarity index 90% rename from define-slow-query-trigger-rules.md rename to config-slow-query-trigger-rules.md index d0db507629ee2..96e8ec6c78631 100644 --- a/define-slow-query-trigger-rules.md +++ b/config-slow-query-trigger-rules.md @@ -5,14 +5,6 @@ summary: Define the trigger rules for slow query logs. # Configure Trigger Rules for Slow Queries - - -This document describes how to use [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-new-in-v856) to define the trigger rules for slow queries displayed in [**Slow Query**](/tidb-cloud/tune-performance.md#slow-query) page in the TiDB Cloud console. - -[`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-new-in-v856) supports multi-dimensional metric combinations. It is suitable for "targeted sampling" and "problem reproduction" of slow queries, enabling you to filter target statements based on specific metric combinations. - - - This document describes how to use [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-new-in-v856) to define the trigger rules for slow query logs. @@ -24,6 +16,15 @@ For TiDB Self-Managed, the triggering behavior of slow query logs depends on the - 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, the configured rules take precedence, and [`tidb_slow_log_threshold`](/system-variables.md#tidb_slow_log_threshold) will be ignored. + + + +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. + +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-new-in-v856) system variable. + +[`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-new-in-v856) supports multi-dimensional metric combinations. It is suitable for "targeted sampling" and "problem reproduction" of slow queries, enabling you to filter target statements based on specific metric combinations. + ## Unified rule syntax and type constraints @@ -118,6 +119,8 @@ The fields in the following table follow the general matching and type rules des SET SESSION tidb_slow_log_rules = 'Conn_ID: 12, Query_time: 0.5, Is_internal: false'; ``` + + - Global rule (applies to all connections): ```sql @@ -130,8 +133,20 @@ The fields in the following table follow the general matching and type rules des SET GLOBAL tidb_slow_log_rules = 'Conn_ID: 11, Query_time: 0.5, Is_internal: false; Conn_ID: 12, Query_time: 0.6, Process_time: 0.3, DB: db1'; ``` + + ## Recommendations + + + - `tidb_slow_log_rules` is designed to replace the single-threshold approach. It supports combinations of multi-dimensional metric conditions, enabling more flexible and fine-grained control over slow query logging. - In a well-provisioned test environment with 1 TiDB node (16 CPU cores, 48 GiB memory) and 3 TiKV nodes (each with 16 CPU cores and 48 GiB memory), repeated sysbench tests show that performance impact remains small when multi-dimensional slow query log rules generate millions of slow log entries within 30 minutes. However, when the log volume reaches tens of millions, TPS drops significantly and latency increases noticeably. Therefore, if business workload is high or CPU and memory resources are close to their limits, configure `tidb_slow_log_rules` carefully to avoid log flooding caused by overly broad rules. If you need to limit the log output rate, use [`tidb_slow_log_max_per_sec`](/system-variables.md#tidb_slow_log_max_per_sec-new-in-v856) to throttle it and reduce the impact on business performance. + + + + +In a well-provisioned test environment with 1 TiDB node (16 CPU cores, 48 GiB memory) and 3 TiKV nodes (each with 16 CPU cores and 48 GiB memory), repeated sysbench tests show that performance impact remains small when multi-dimensional slow query log rules generate millions of slow log entries within 30 minutes. However, when the log volume reaches tens of millions, TPS drops significantly and latency increases noticeably. Therefore, if business workload is high or CPU and memory resources are close to their limits, configure `tidb_slow_log_rules` carefully to avoid log flooding caused by overly broad rules. + + \ No newline at end of file diff --git a/system-variables.md b/system-variables.md index 818098f05e9d7..a162a4382de10 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5995,7 +5995,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) - Default value: "" - Type: String - This variable defines the triggering rules for slow query logs. It supports combining multi-dimensional metrics to provide more flexible and fine-grained logging. -- For more information about how to use this system variable, see [Use `tidb_slow_log_rules`](/identify-slow-queries.md#use-tidb_slow_log_rules). +- For more information about how to use this system variable, see [Configure Trigger Rules for Slow Queries](/config-slow-query-trigger-rules.md). From a3d6a23326d8f51936272fc5a28b57b9aa1601c4 Mon Sep 17 00:00:00 2001 From: qiancai Date: Tue, 8 Sep 2026 10:07:25 +0800 Subject: [PATCH 05/18] Update config-slow-query-trigger-rules.md --- config-slow-query-trigger-rules.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/config-slow-query-trigger-rules.md b/config-slow-query-trigger-rules.md index 96e8ec6c78631..50dd081cd0301 100644 --- a/config-slow-query-trigger-rules.md +++ b/config-slow-query-trigger-rules.md @@ -7,7 +7,7 @@ summary: Define the trigger rules for slow query logs. -This document describes how to use [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-new-in-v856) to define the trigger rules for slow query logs. +This document describes how to use the [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-new-in-v856) system variable to define the trigger rules for [slow query logs](/identify-slow-queries.md). [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-new-in-v856) supports multi-dimensional metric combinations. It is suitable for "targeted sampling" and "problem reproduction" of slow query logs, enabling you to filter target statements based on specific metric combinations. @@ -19,7 +19,7 @@ For TiDB Self-Managed, the triggering behavior of slow query logs depends on the -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. +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-new-in-v856) system variable. @@ -135,18 +135,24 @@ The fields in the following table follow the general matching and type rules des -## Recommendations + - +- Global rule (applies to all connections): + ```sql + SET GLOBAL tidb_slow_log_rules = 'Query_time: 0.5, Is_internal: false'; + ``` -- `tidb_slow_log_rules` is designed to replace the single-threshold approach. It supports combinations of multi-dimensional metric conditions, enabling more flexible and fine-grained control over slow query logging. +- Global rules for specific connections (applied separately to the two connections `Conn_ID:11` and `Conn_ID:12`): -- In a well-provisioned test environment with 1 TiDB node (16 CPU cores, 48 GiB memory) and 3 TiKV nodes (each with 16 CPU cores and 48 GiB memory), repeated sysbench tests show that performance impact remains small when multi-dimensional slow query log rules generate millions of slow log entries within 30 minutes. However, when the log volume reaches tens of millions, TPS drops significantly and latency increases noticeably. Therefore, if business workload is high or CPU and memory resources are close to their limits, configure `tidb_slow_log_rules` carefully to avoid log flooding caused by overly broad rules. If you need to limit the log output rate, use [`tidb_slow_log_max_per_sec`](/system-variables.md#tidb_slow_log_max_per_sec-new-in-v856) to throttle it and reduce the impact on business performance. + ```sql + SET GLOBAL tidb_slow_log_rules = 'Conn_ID: 11, Query_time: 0.5, Is_internal: false; Conn_ID: 12, Query_time: 0.6, Process_time: 0.3, DB: db1'; + ``` - -In a well-provisioned test environment with 1 TiDB node (16 CPU cores, 48 GiB memory) and 3 TiKV nodes (each with 16 CPU cores and 48 GiB memory), repeated sysbench tests show that performance impact remains small when multi-dimensional slow query log rules generate millions of slow log entries within 30 minutes. However, when the log volume reaches tens of millions, TPS drops significantly and latency increases noticeably. Therefore, if business workload is high or CPU and memory resources are close to their limits, configure `tidb_slow_log_rules` carefully to avoid log flooding caused by overly broad rules. +## Recommendations + +- `tidb_slow_log_rules` is designed to replace the single-threshold approach. It supports combinations of multi-dimensional metric conditions, enabling more flexible and fine-grained control over slow query logging. - \ No newline at end of file +- In a well-provisioned test environment with 1 TiDB node (16 CPU cores, 48 GiB memory) and 3 TiKV nodes (each with 16 CPU cores and 48 GiB memory), repeated sysbench tests show that performance impact remains small when multi-dimensional slow query log rules generate millions of slow log entries within 30 minutes. However, when the log volume reaches tens of millions, TPS drops significantly and latency increases noticeably. Therefore, if business workload is high or CPU and memory resources are close to their limits, configure `tidb_slow_log_rules` carefully to avoid log flooding caused by overly broad rules. If you need to limit the log output rate, use [`tidb_slow_log_max_per_sec`](/system-variables.md#tidb_slow_log_max_per_sec-new-in-v856) to throttle it and reduce the impact on business performance. \ No newline at end of file From 05773ffd87abefb78d2cd83e467b38dd511bd2d4 Mon Sep 17 00:00:00 2001 From: qiancai Date: Tue, 8 Sep 2026 10:22:19 +0800 Subject: [PATCH 06/18] update Effective behavior and matching order --- config-slow-query-trigger-rules.md | 42 ++++++++++++++++++++++++------ 1 file changed, 34 insertions(+), 8 deletions(-) diff --git a/config-slow-query-trigger-rules.md b/config-slow-query-trigger-rules.md index 50dd081cd0301..13b6a8ad7727d 100644 --- a/config-slow-query-trigger-rules.md +++ b/config-slow-query-trigger-rules.md @@ -95,16 +95,42 @@ The fields in the following table follow the general matching and type rules des ## Effective behavior and matching order -- Rule update behavior: every execution of `SET [SESSION|GLOBAL] tidb_slow_log_rules = '...'` overwrites the existing rules in that scope instead of appending to them. -- Rule clearing behavior: `SET [SESSION|GLOBAL] tidb_slow_log_rules = ''` clears the rules in the corresponding scope. -- If the current session has any applicable `tidb_slow_log_rules`, such as `SESSION` rules, `GLOBAL` rules for the current `Conn_ID`, or generic global rules without `Conn_ID`, the output of slow query logs is determined by rule matching results, and `tidb_slow_log_threshold` is no longer used. -- If the current session has no applicable rules, for example when both `SESSION` and `GLOBAL` rules are empty, or only `GLOBAL` rules that do not match the current `Conn_ID` are configured, slow query logging still depends on `tidb_slow_log_threshold`. Note that the unit is milliseconds. +- Setting `tidb_slow_log_rules` overwrites the existing rules in the specified scope instead of appending new rules. +- Setting `tidb_slow_log_rules` to an empty string clears the rules in the specified scope. +- Multiple rules are combined with `OR`, while multiple field conditions within a single rule are combined with `AND`. - If you still want to use SQL execution time as a condition for writing slow query logs, use `Query_time` in the rule and note that the unit is seconds. -- Rule matching logic: - - Multiple rules are combined with `OR`, while multiple field conditions within a single rule are combined with `AND`. - - `SESSION`-scope rules are matched first. If none matches, TiDB then matches `GLOBAL` rules for the current `Conn_ID`, followed by generic `GLOBAL` rules without `Conn_ID`. + + + +TiDB Self-Managed supports both `SESSION` and `GLOBAL` rules for `tidb_slow_log_rules`. + +- If the current session has any applicable rules, such as `SESSION` rules, `GLOBAL` rules for the current `Conn_ID`, or generic `GLOBAL` rules without `Conn_ID`, slow query log output is determined by the rule matching results, and `tidb_slow_log_threshold` is ignored. +- If the current session has no applicable rules, for example, when both `SESSION` and `GLOBAL` rules are empty or only `GLOBAL` rules that do not match the current `Conn_ID` are configured, slow query logging still depends on `tidb_slow_log_threshold`. The unit of `tidb_slow_log_threshold` is milliseconds. +- TiDB matches `SESSION` rules first. If none matches, TiDB then matches `GLOBAL` rules for the current `Conn_ID`, followed by generic `GLOBAL` rules without `Conn_ID`. +- `SHOW VARIABLES LIKE 'tidb_slow_log_rules'` and `SELECT @@SESSION.tidb_slow_log_rules` return the `SESSION` rule text, or an empty string if unset. `SELECT @@GLOBAL.tidb_slow_log_rules` returns the `GLOBAL` rule text. + + + + + +TiDB Cloud Dedicated supports both `SESSION` and `GLOBAL` rules for `tidb_slow_log_rules`. + +- If the current session has any applicable rules, such as `SESSION` rules, `GLOBAL` rules for the current `Conn_ID`, or generic `GLOBAL` rules without `Conn_ID`, slow query log output is determined by the rule matching results. +- If the current session has no applicable rules, for example, when both `SESSION` and `GLOBAL` rules are empty or only `GLOBAL` rules that do not match the current `Conn_ID` are configured, the rules for slow query logging fall back to the default one: SQL queries that take more than 300 milliseconds are considered as slow queries. +- TiDB matches `SESSION` rules first. If none matches, TiDB then matches `GLOBAL` rules for the current `Conn_ID`, followed by generic `GLOBAL` rules without `Conn_ID`. - `SHOW VARIABLES LIKE 'tidb_slow_log_rules'` and `SELECT @@SESSION.tidb_slow_log_rules` return the `SESSION` rule text, or an empty string if unset. `SELECT @@GLOBAL.tidb_slow_log_rules` returns the `GLOBAL` rule text. + + + + +TiDB Cloud Essential and TiDB Cloud Premium support only `SESSION` rules for `tidb_slow_log_rules`. + +- If the current session has any `SESSION` rules, slow query log output is determined by the rule matching results. +- `SHOW VARIABLES LIKE 'tidb_slow_log_rules'` and `SELECT @@SESSION.tidb_slow_log_rules` return the `SESSION` rule text, or an empty string if unset. + + + ## Examples - Standard format (`SESSION` scope): @@ -155,4 +181,4 @@ The fields in the following table follow the general matching and type rules des - `tidb_slow_log_rules` is designed to replace the single-threshold approach. It supports combinations of multi-dimensional metric conditions, enabling more flexible and fine-grained control over slow query logging. -- In a well-provisioned test environment with 1 TiDB node (16 CPU cores, 48 GiB memory) and 3 TiKV nodes (each with 16 CPU cores and 48 GiB memory), repeated sysbench tests show that performance impact remains small when multi-dimensional slow query log rules generate millions of slow log entries within 30 minutes. However, when the log volume reaches tens of millions, TPS drops significantly and latency increases noticeably. Therefore, if business workload is high or CPU and memory resources are close to their limits, configure `tidb_slow_log_rules` carefully to avoid log flooding caused by overly broad rules. If you need to limit the log output rate, use [`tidb_slow_log_max_per_sec`](/system-variables.md#tidb_slow_log_max_per_sec-new-in-v856) to throttle it and reduce the impact on business performance. \ No newline at end of file +- In a well-provisioned test environment with 1 TiDB node (16 CPU cores, 48 GiB memory) and 3 TiKV nodes (each with 16 CPU cores and 48 GiB memory), repeated sysbench tests show that performance impact remains small when multi-dimensional slow query log rules generate millions of slow log entries within 30 minutes. However, when the log volume reaches tens of millions, TPS drops significantly and latency increases noticeably. Therefore, if business workload is high or CPU and memory resources are close to their limits, configure `tidb_slow_log_rules` carefully to avoid log flooding caused by overly broad rules. If you need to limit the log output rate, use [`tidb_slow_log_max_per_sec`](/system-variables.md#tidb_slow_log_max_per_sec-new-in-v856) to throttle it and reduce the impact on business performance. From a25e6acccbe07363a62425ade079ff3653d5fcd1 Mon Sep 17 00:00:00 2001 From: qiancai Date: Tue, 8 Sep 2026 10:26:51 +0800 Subject: [PATCH 07/18] Update config-slow-query-trigger-rules.md --- config-slow-query-trigger-rules.md | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/config-slow-query-trigger-rules.md b/config-slow-query-trigger-rules.md index 13b6a8ad7727d..417c60b974f88 100644 --- a/config-slow-query-trigger-rules.md +++ b/config-slow-query-trigger-rules.md @@ -29,9 +29,28 @@ By default, SQL queries that take more than 300 milliseconds are considered as s ## Unified rule syntax and type constraints -- Rule capacity and separation: `SESSION` and `GLOBAL` each support a maximum of 10 rules. A single session can have up to 20 active rules. Rules are separated by `;`. +- Rule capacity and separation: each supported scope can contain a maximum of 10 rules. Rules are separated by `;`. - Condition format: each condition uses the format `field_name:value`. Multiple conditions within a single rule are separated by `,`. -- Field and scope: field names are case-insensitive (underscores and other characters are preserved). `SESSION` rules do not support `Conn_ID`. Only `GLOBAL` rules support `Conn_ID`. +- Field names are case-insensitive. Underscores and other characters in field names are preserved. + + + +TiDB Self-Managed supports both `SESSION` and `GLOBAL` rules for `tidb_slow_log_rules`. A single session can have up to 20 active rules across the two scopes. `SESSION` rules do not support `Conn_ID`; only `GLOBAL` rules support this field. + + + + + +TiDB Cloud Dedicated supports both `SESSION` and `GLOBAL` rules for `tidb_slow_log_rules`. A single session can have up to 20 active rules across the two scopes. `SESSION` rules do not support `Conn_ID`; only `GLOBAL` rules support this field. + + + + + +TiDB Cloud Essential and TiDB Cloud Premium support only `SESSION` rules for `tidb_slow_log_rules`. Therefore, `Conn_ID`, which is available only in `GLOBAL` rules, is not supported. + + + - Matching semantics: - Numeric fields are matched using `>=`. String and boolean fields are matched using equality (`=`). - Matching for `DB` and `Resource_group` is case-insensitive. From 86ad6df753a5650f2e52c6a87d9d4e1747aee04f Mon Sep 17 00:00:00 2001 From: qiancai Date: Tue, 8 Sep 2026 10:32:16 +0800 Subject: [PATCH 08/18] fix links to slow query trigger rules --- TOC-tidb-cloud-essential.md | 2 +- TOC-tidb-cloud-premium.md | 2 +- TOC.md | 2 +- system-variables.md | 4 ++-- tidb-cloud/tune-performance.md | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/TOC-tidb-cloud-essential.md b/TOC-tidb-cloud-essential.md index 2115391850125..bbf467c97e340 100644 --- a/TOC-tidb-cloud-essential.md +++ b/TOC-tidb-cloud-essential.md @@ -557,7 +557,7 @@ - [Server Status Variables](/status-variables.md) - [Table Filter](/table-filter.md) - [URI Formats of External Storage Services](/external-storage-uri.md) - - [Configure Trigger Rules for Slow Queries](/define-slow-query-trigger-rules.md) + - [Configure Trigger Rules for Slow Queries](/config-slow-query-trigger-rules.md) - [Troubleshoot Inconsistency Between Data and Indexes](/troubleshoot-data-inconsistency-errors.md) - [Notifications](/tidb-cloud/notifications.md) - [Project API Migration Guide for {{{ .starter }}} and Essential](/tidb-cloud/tidbx-starter-essential-project-api-migration-guide.md) diff --git a/TOC-tidb-cloud-premium.md b/TOC-tidb-cloud-premium.md index 8ed3fbe711bd6..73aa1ebc6c10e 100644 --- a/TOC-tidb-cloud-premium.md +++ b/TOC-tidb-cloud-premium.md @@ -479,7 +479,7 @@ - [Table Filter](/table-filter.md) - [URI Formats of External Storage Services](/external-storage-uri.md) - [`ANALYZE` Embedded in DDL Statements](/ddl_embedded_analyze.md) - - [Configure Trigger Rules for Slow Queries](/define-slow-query-trigger-rules.md) + - [Configure Trigger Rules for Slow Queries](/config-slow-query-trigger-rules.md) - [Troubleshoot Inconsistency Between Data and Indexes](/troubleshoot-data-inconsistency-errors.md) - [Notifications](/tidb-cloud/notifications.md) - Support Plan diff --git a/TOC.md b/TOC.md index d7afb235545a8..3dde182c31e3b 100644 --- a/TOC.md +++ b/TOC.md @@ -213,7 +213,7 @@ - Issue Scenarios - Slow Queries - [Identify Slow Queries](/identify-slow-queries.md) - - [Configure Trigger Rules for Slow Queries](/define-slow-query-trigger-rules.md) + - [Configure Trigger Rules for Slow Queries](/config-slow-query-trigger-rules.md) - [Analyze Slow Queries](/analyze-slow-queries.md) - [TiDB OOM](/troubleshoot-tidb-oom.md) - [Hotspot](/troubleshoot-hot-spot-issues.md) diff --git a/system-variables.md b/system-variables.md index a162a4382de10..bd3072e43bb60 100644 --- a/system-variables.md +++ b/system-variables.md @@ -6002,14 +6002,14 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) > **Tip:** > > - When enabling `tidb_slow_log_rules` in a production environment, it is recommended to also configure [`tidb_slow_log_max_per_sec`](#tidb_slow_log_max_per_sec-new-in-v856) to avoid excessively frequent slow query log printing. -> - It is recommended to start with stricter conditions and gradually relax them based on troubleshooting needs. For more information on performance impact, see [Recommendations](/identify-slow-queries.md#recommendations). +> - It is recommended to start with stricter conditions and gradually relax them based on troubleshooting needs. For more information on performance impact, see [Recommendations](/config-slow-query-trigger-rules.md#recommendations). > **Tip:** > -> It is recommended to start with stricter conditions and gradually relax them based on troubleshooting needs. For more information on performance impact, see [Recommendations](/identify-slow-queries.md#recommendations). +> It is recommended to start with stricter conditions and gradually relax them based on troubleshooting needs. For more information on performance impact, see [Recommendations](/config-slow-query-trigger-rules.md#recommendations). diff --git a/tidb-cloud/tune-performance.md b/tidb-cloud/tune-performance.md index b7ba8d9e9f86d..422c242885f41 100644 --- a/tidb-cloud/tune-performance.md +++ b/tidb-cloud/tune-performance.md @@ -50,7 +50,7 @@ By default, SQL queries that take more than 300 milliseconds are considered as s > **Note:** > -> You can also configure trigger rules for slow queries to filter target statements based on specific metric combinations. For more information, see [Configure Trigger Rules for Slow Queries](/define-slow-query-trigger-rules.md). +> You can also configure trigger rules for slow queries to filter target statements based on specific metric combinations. For more information, see [Configure Trigger Rules for Slow Queries](/config-slow-query-trigger-rules.md). From b36989392629cdf6f21974614caa9a3d9da5370c Mon Sep 17 00:00:00 2001 From: qiancai Date: Tue, 8 Sep 2026 10:48:56 +0800 Subject: [PATCH 09/18] reorder slow query trigger rule examples --- config-slow-query-trigger-rules.md | 92 +++++++++++++++--------------- 1 file changed, 46 insertions(+), 46 deletions(-) diff --git a/config-slow-query-trigger-rules.md b/config-slow-query-trigger-rules.md index 417c60b974f88..c5245e85bcbbb 100644 --- a/config-slow-query-trigger-rules.md +++ b/config-slow-query-trigger-rules.md @@ -27,6 +27,52 @@ By default, SQL queries that take more than 300 milliseconds are considered as s +## Examples + +- Standard format (`SESSION` scope): + + ```sql + SET SESSION tidb_slow_log_rules = 'Query_time: 0.5, Is_internal: false'; + ``` + +- Invalid format (`SESSION` scope does not support `Conn_ID`): + + ```sql + SET SESSION tidb_slow_log_rules = 'Conn_ID: 12, Query_time: 0.5, Is_internal: false'; + ``` + + + +- Global rule (applies to all connections): + + ```sql + SET GLOBAL tidb_slow_log_rules = 'Query_time: 0.5, Is_internal: false'; + ``` + +- Global rules for specific connections (applied separately to the two connections `Conn_ID:11` and `Conn_ID:12`): + + ```sql + SET GLOBAL tidb_slow_log_rules = 'Conn_ID: 11, Query_time: 0.5, Is_internal: false; Conn_ID: 12, Query_time: 0.6, Process_time: 0.3, DB: db1'; + ``` + + + + + +- Global rule (applies to all connections): + + ```sql + SET GLOBAL tidb_slow_log_rules = 'Query_time: 0.5, Is_internal: false'; + ``` + +- Global rules for specific connections (applied separately to the two connections `Conn_ID:11` and `Conn_ID:12`): + + ```sql + SET GLOBAL tidb_slow_log_rules = 'Conn_ID: 11, Query_time: 0.5, Is_internal: false; Conn_ID: 12, Query_time: 0.6, Process_time: 0.3, DB: db1'; + ``` + + + ## Unified rule syntax and type constraints - Rule capacity and separation: each supported scope can contain a maximum of 10 rules. Rules are separated by `;`. @@ -150,52 +196,6 @@ TiDB Cloud Essential and TiDB Cloud Premium support only `SESSION` rules for `ti -## Examples - -- Standard format (`SESSION` scope): - - ```sql - SET SESSION tidb_slow_log_rules = 'Query_time: 0.5, Is_internal: false'; - ``` - -- Invalid format (`SESSION` scope does not support `Conn_ID`): - - ```sql - SET SESSION tidb_slow_log_rules = 'Conn_ID: 12, Query_time: 0.5, Is_internal: false'; - ``` - - - -- Global rule (applies to all connections): - - ```sql - SET GLOBAL tidb_slow_log_rules = 'Query_time: 0.5, Is_internal: false'; - ``` - -- Global rules for specific connections (applied separately to the two connections `Conn_ID:11` and `Conn_ID:12`): - - ```sql - SET GLOBAL tidb_slow_log_rules = 'Conn_ID: 11, Query_time: 0.5, Is_internal: false; Conn_ID: 12, Query_time: 0.6, Process_time: 0.3, DB: db1'; - ``` - - - - - -- Global rule (applies to all connections): - - ```sql - SET GLOBAL tidb_slow_log_rules = 'Query_time: 0.5, Is_internal: false'; - ``` - -- Global rules for specific connections (applied separately to the two connections `Conn_ID:11` and `Conn_ID:12`): - - ```sql - SET GLOBAL tidb_slow_log_rules = 'Conn_ID: 11, Query_time: 0.5, Is_internal: false; Conn_ID: 12, Query_time: 0.6, Process_time: 0.3, DB: db1'; - ``` - - - ## Recommendations - `tidb_slow_log_rules` is designed to replace the single-threshold approach. It supports combinations of multi-dimensional metric conditions, enabling more flexible and fine-grained control over slow query logging. From 425878af3e6f4899796cd599f7bf77aac9fefc44 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Tue, 8 Sep 2026 11:02:08 +0800 Subject: [PATCH 10/18] Update config-slow-query-trigger-rules.md --- config-slow-query-trigger-rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config-slow-query-trigger-rules.md b/config-slow-query-trigger-rules.md index c5245e85bcbbb..1a10dca50e427 100644 --- a/config-slow-query-trigger-rules.md +++ b/config-slow-query-trigger-rules.md @@ -14,7 +14,7 @@ This document describes how to use the [`tidb_slow_log_rules`](/system-variables 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, the configured rules take precedence, and [`tidb_slow_log_threshold`](/system-variables.md#tidb_slow_log_threshold) will be ignored. +- 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. From 553d9c03fa3a7a33e935a3b06e64c9ceb7ae71ce Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Tue, 8 Sep 2026 11:03:16 +0800 Subject: [PATCH 11/18] Update config-slow-query-trigger-rules.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- config-slow-query-trigger-rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config-slow-query-trigger-rules.md b/config-slow-query-trigger-rules.md index 1a10dca50e427..a69b591dc25af 100644 --- a/config-slow-query-trigger-rules.md +++ b/config-slow-query-trigger-rules.md @@ -35,7 +35,7 @@ By default, SQL queries that take more than 300 milliseconds are considered as s SET SESSION tidb_slow_log_rules = 'Query_time: 0.5, Is_internal: false'; ``` -- Invalid format (`SESSION` scope does not support `Conn_ID`): +- Invalid `SESSION` rule (`SESSION` scope does not support `Conn_ID`): ```sql SET SESSION tidb_slow_log_rules = 'Conn_ID: 12, Query_time: 0.5, Is_internal: false'; From 2a8ed9f46bf905bd9a484bedb3554710923d6f5c Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Tue, 8 Sep 2026 11:12:47 +0800 Subject: [PATCH 12/18] Update config-slow-query-trigger-rules.md --- config-slow-query-trigger-rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config-slow-query-trigger-rules.md b/config-slow-query-trigger-rules.md index a69b591dc25af..a9a054ea50960 100644 --- a/config-slow-query-trigger-rules.md +++ b/config-slow-query-trigger-rules.md @@ -104,7 +104,7 @@ TiDB Cloud Essential and TiDB Cloud Premium support only `SESSION` rules for `ti Type constraints are as follows: -- Numeric types (`int64`, `uint64`, `float64`) uniformly require `>= 0`. Negative values will result in a parsing error. +- 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. From 2aef3db368daffb0db659f98caffcbd4e159a686 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Wed, 9 Sep 2026 11:15:18 +0800 Subject: [PATCH 13/18] Apply suggestions from code review --- config-slow-query-trigger-rules.md | 6 +++--- identify-slow-queries.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/config-slow-query-trigger-rules.md b/config-slow-query-trigger-rules.md index a9a054ea50960..af567fe3259cc 100644 --- a/config-slow-query-trigger-rules.md +++ b/config-slow-query-trigger-rules.md @@ -13,8 +13,8 @@ This document describes how to use the [`tidb_slow_log_rules`](/system-variables 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. +- If the current session has no applicable `tidb_slow_log_rules` rule (either because this variable is not set or because none of the configured rules apply to the session), slow query logging still relies on [`tidb_slow_log_threshold`](/system-variables.md#tidb_slow_log_threshold) (in milliseconds). +- If the current session has any applicable `tidb_slow_log_rules` rules, slow query logging is determined by the rule matching results, and [`tidb_slow_log_threshold`](/system-variables.md#tidb_slow_log_threshold) is ignored. @@ -107,7 +107,7 @@ Type constraints are as follows: - 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. + - `float64`: values must be finite and non-negative. The maximum value is approximately `1.79e308`. `NaN` and infinite values such as `Inf` and `-Inf` are invalid and result in an error. - `bool`: supports `true`/`false`, `1`/`0`, and `t`/`f` (case-insensitive). - `string`: currently does not support strings containing the separators `,` (condition separator) or `;` (rule separator), even with quotes (single or double). Escaping is not supported. - Duplicate fields: if the same field is specified multiple times in a single rule, the last occurrence takes effect. diff --git a/identify-slow-queries.md b/identify-slow-queries.md index bf3c45545064f..3bff6363926d1 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -174,7 +174,7 @@ Fields related to storage engines: ## Related system variables -* [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-new-in-v856): see [`tidb_slow_log_rules` recommendations](#recommendations) +* [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-new-in-v856): see [`tidb_slow_log_rules` recommendations](/config-slow-query-trigger-rules.md#recommendations) * [`tidb_slow_log_threshold`](/system-variables.md#tidb_slow_log_threshold): sets the threshold for slow query logging. SQL statements whose execution time exceeds this threshold are recorded in the slow query log. The default value is `300ms` (milliseconds). From 41236dc460125f997ed224d2dba57ee056a6d753 Mon Sep 17 00:00:00 2001 From: qiancai Date: Wed, 9 Sep 2026 11:55:32 +0800 Subject: [PATCH 14/18] fix broken links for the two variables --- config-slow-query-trigger-rules.md | 10 +++++----- identify-slow-queries.md | 4 ++-- releases/release-8.5.6.md | 6 +++--- system-variables.md | 12 ++++++++---- 4 files changed, 18 insertions(+), 14 deletions(-) diff --git a/config-slow-query-trigger-rules.md b/config-slow-query-trigger-rules.md index af567fe3259cc..37e1843efbdda 100644 --- a/config-slow-query-trigger-rules.md +++ b/config-slow-query-trigger-rules.md @@ -7,9 +7,9 @@ summary: Define the trigger rules for slow query logs. -This document describes how to use the [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-new-in-v856) system variable to define the trigger rules for [slow query logs](/identify-slow-queries.md). +This document describes how to use the [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules) system variable to define the trigger rules for [slow query logs](/identify-slow-queries.md). -[`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-new-in-v856) supports multi-dimensional metric combinations. It is suitable for "targeted sampling" and "problem reproduction" of slow query logs, enabling you to filter target statements based on specific metric combinations. +[`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules) supports multi-dimensional metric combinations. It is suitable for "targeted sampling" and "problem reproduction" of slow query logs, enabling you to filter target statements based on specific metric combinations. For TiDB Self-Managed, the triggering behavior of slow query logs depends on the configuration of `tidb_slow_log_rules`: @@ -21,9 +21,9 @@ For TiDB Self-Managed, the triggering behavior of slow query logs depends on the 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-new-in-v856) system variable. +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. -[`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-new-in-v856) supports multi-dimensional metric combinations. It is suitable for "targeted sampling" and "problem reproduction" of slow queries, enabling you to filter target statements based on specific metric combinations. +[`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules) supports multi-dimensional metric combinations. It is suitable for "targeted sampling" and "problem reproduction" of slow queries, enabling you to filter target statements based on specific metric combinations. @@ -200,4 +200,4 @@ TiDB Cloud Essential and TiDB Cloud Premium support only `SESSION` rules for `ti - `tidb_slow_log_rules` is designed to replace the single-threshold approach. It supports combinations of multi-dimensional metric conditions, enabling more flexible and fine-grained control over slow query logging. -- In a well-provisioned test environment with 1 TiDB node (16 CPU cores, 48 GiB memory) and 3 TiKV nodes (each with 16 CPU cores and 48 GiB memory), repeated sysbench tests show that performance impact remains small when multi-dimensional slow query log rules generate millions of slow log entries within 30 minutes. However, when the log volume reaches tens of millions, TPS drops significantly and latency increases noticeably. Therefore, if business workload is high or CPU and memory resources are close to their limits, configure `tidb_slow_log_rules` carefully to avoid log flooding caused by overly broad rules. If you need to limit the log output rate, use [`tidb_slow_log_max_per_sec`](/system-variables.md#tidb_slow_log_max_per_sec-new-in-v856) to throttle it and reduce the impact on business performance. +- In a well-provisioned test environment with 1 TiDB node (16 CPU cores, 48 GiB memory) and 3 TiKV nodes (each with 16 CPU cores and 48 GiB memory), repeated sysbench tests show that performance impact remains small when multi-dimensional slow query log rules generate millions of slow log entries within 30 minutes. However, when the log volume reaches tens of millions, TPS drops significantly and latency increases noticeably. Therefore, if business workload is high or CPU and memory resources are close to their limits, configure `tidb_slow_log_rules` carefully to avoid log flooding caused by overly broad rules. If you need to limit the log output rate, use [`tidb_slow_log_max_per_sec`](/system-variables.md#tidb_slow_log_max_per_sec) to throttle it and reduce the impact on business performance. diff --git a/identify-slow-queries.md b/identify-slow-queries.md index 3bff6363926d1..42654948b17bd 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -174,7 +174,7 @@ Fields related to storage engines: ## Related system variables -* [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-new-in-v856): see [`tidb_slow_log_rules` recommendations](/config-slow-query-trigger-rules.md#recommendations) +* [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules): see [`tidb_slow_log_rules` recommendations](/config-slow-query-trigger-rules.md#recommendations) * [`tidb_slow_log_threshold`](/system-variables.md#tidb_slow_log_threshold): sets the threshold for slow query logging. SQL statements whose execution time exceeds this threshold are recorded in the slow query log. The default value is `300ms` (milliseconds). @@ -182,7 +182,7 @@ Fields related to storage engines: > > Time-related fields in `tidb_slow_log_rules`, such as `Query_time` and `Process_time`, use seconds as the unit and can include decimals, while [`tidb_slow_log_threshold`](/system-variables.md#tidb_slow_log_threshold) uses milliseconds. -* [`tidb_slow_log_max_per_sec`](/system-variables.md#tidb_slow_log_max_per_sec-new-in-v856): sets the maximum number of slow query log entries that can be written per second. The default value is `0`. This variable is introduced in v8.5.6. +* [`tidb_slow_log_max_per_sec`](/system-variables.md#tidb_slow_log_max_per_sec): sets the maximum number of slow query log entries that can be written per second. The default value is `0`. This variable is introduced in v8.5.6. * A value of `0` means there is no limit on the number of slow query log entries written per second. * A value greater than `0` means TiDB writes at most the specified number of slow query log entries per second. Any excess log entries are discarded and not written to the slow query log file. * It is recommended to set this variable after enabling `tidb_slow_log_rules` to prevent rule-based slow query logging from being triggered too frequently. diff --git a/releases/release-8.5.6.md b/releases/release-8.5.6.md index 2690f6fdf4db9..e218c4076b086 100644 --- a/releases/release-8.5.6.md +++ b/releases/release-8.5.6.md @@ -40,7 +40,7 @@ Quick access: [Quick start](https://docs.pingcap.com/tidb/v8.5/quick-start-with- Before v8.5.6, the main way to identify slow queries in TiDB is to set the [`tidb_slow_log_threshold`](https://docs.pingcap.com/tidb/v8.5/system-variables#tidb_slow_log_threshold) system variable. This mechanism provides only coarse-grained control over slow query log triggering because it applies globally at the instance level and does not support fine-grained control at the session or SQL level. In addition, it supports only one trigger condition, execution time (`Query_time`), which cannot meet the need to capture slow query logs more precisely in complex scenarios. - Starting from v8.5.6, TiDB enhances slow query log control. You can use the [`tidb_slow_log_rules`](https://docs.pingcap.com/tidb/v8.5/system-variables#tidb_slow_log_rules-new-in-v856) system variable to define multi-dimensional slow query log output rules at the instance, session, and SQL levels, based on conditions such as `Query_time`, `Digest`, `Mem_max`, and `KV_total`. You can use [`tidb_slow_log_max_per_sec`](https://docs.pingcap.com/tidb/v8.5/system-variables#tidb_slow_log_max_per_sec-new-in-v856) to limit the number of log entries written per second, and use the [`WRITE_SLOW_LOG`](https://docs.pingcap.com/tidb/v8.5/optimizer-hints) hint to force slow query logging for specific SQL statements. This enables more flexible and fine-grained control over slow query logs. + Starting from v8.5.6, TiDB enhances slow query log control. You can use the [`tidb_slow_log_rules`](https://docs.pingcap.com/tidb/v8.5/system-variables#tidb_slow_log_rules) system variable to define multi-dimensional slow query log output rules at the instance, session, and SQL levels, based on conditions such as `Query_time`, `Digest`, `Mem_max`, and `KV_total`. You can use [`tidb_slow_log_max_per_sec`](https://docs.pingcap.com/tidb/v8.5/system-variables#tidb_slow_log_max_per_sec) to limit the number of log entries written per second, and use the [`WRITE_SLOW_LOG`](https://docs.pingcap.com/tidb/v8.5/optimizer-hints) hint to force slow query logging for specific SQL statements. This enables more flexible and fine-grained control over slow query logs. For more information, see [documentation](https://docs.pingcap.com/tidb/v8.5/identify-slow-queries). @@ -99,8 +99,8 @@ For TiDB clusters newly deployed in v8.5.5 (that is, not upgraded from versions | [`tidb_foreign_key_check_in_shared_lock`](https://docs.pingcap.com/tidb/v8.5/system-variables#tidb_foreign_key_check_in_shared_lock-new-in-v856) | Newly added | Controls whether foreign key checks in pessimistic transactions use shared locks instead of exclusive locks on rows in the parent table. The default value is `OFF`, which means TiDB uses exclusive locks by default. | | [`tidb_max_dist_task_nodes`](https://docs.pingcap.com/tidb/v8.5/system-variables#tidb_max_dist_task_nodes-new-in-v856) | Newly added | Defines the maximum number of TiDB nodes that the Distributed eXecution Framework (DXF) tasks can use. The default value is `-1`, which indicates that automatic mode is enabled. In automatic mode, TiDB dynamically calculates the value as `min(3, tikv_nodes / 3)`, where `tikv_nodes` represents the number of TiKV nodes in the cluster. | | [`tidb_opt_join_reorder_through_sel`](https://docs.pingcap.com/tidb/v8.5/system-variables#tidb_opt_join_reorder_through_sel-new-in-v856) | Newly added | Improves join reorder optimization for certain multi-table join queries. If you set it to `ON` and safety conditions are met, the optimizer evaluates `Selection` conditions between consecutive join operators together with join order candidates. During join tree reconstruction, the optimizer pushes these conditions down to more appropriate positions whenever possible, allowing more tables to participate in join order optimization. | -| [`tidb_slow_log_max_per_sec`](https://docs.pingcap.com/tidb/v8.5/system-variables#tidb_slow_log_max_per_sec-new-in-v856) | Newly added | Controls the maximum number of slow query log entries that can be written per TiDB node per second.
  • A value of `0` (the default) means there is no limit on the number of slow query log entries written per second.
  • A value greater than `0` means TiDB writes at most the specified number of slow query log entries per second. Any excess log entries are discarded and not written to the slow query log file.
| -| [`tidb_slow_log_rules`](https://docs.pingcap.com/tidb/v8.5/system-variables#tidb_slow_log_rules-new-in-v856) | Newly added | Defines the triggering rules for slow query logs. It supports combining multi-dimensional metrics to provide more flexible and fine-grained logging. | +| [`tidb_slow_log_max_per_sec`](https://docs.pingcap.com/tidb/v8.5/system-variables#tidb_slow_log_max_per_sec) | Newly added | Controls the maximum number of slow query log entries that can be written per TiDB node per second.
  • A value of `0` (the default) means there is no limit on the number of slow query log entries written per second.
  • A value greater than `0` means TiDB writes at most the specified number of slow query log entries per second. Any excess log entries are discarded and not written to the slow query log file.
| +| [`tidb_slow_log_rules`](https://docs.pingcap.com/tidb/v8.5/system-variables#tidb_slow_log_rules) | Newly added | Defines the triggering rules for slow query logs. It supports combining multi-dimensional metrics to provide more flexible and fine-grained logging. | ### Configuration parameters diff --git a/system-variables.md b/system-variables.md index bd3072e43bb60..2fb1b6f61c671 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5968,7 +5968,11 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) > > If the character check is skipped, TiDB might fail to detect invalid UTF-8 characters written by the application, cause decoding errors when `ANALYZE` is executed, and introduce other unknown encoding issues. If your application cannot guarantee the validity of the written string, it is not recommended to skip the character check. -### tidb_slow_log_max_per_sec New in v8.5.6 +### tidb_slow_log_max_per_sec New in v8.5.6 and CLOUD.202603.1 {#tidb_slow_log_max_per_sec} + +>**Note:** +> +> This variable is read-only for TiDB Cloud. - Scope: GLOBAL - Persists to cluster: Yes @@ -5979,9 +5983,9 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) - This variable controls the maximum number of slow query log entries that can be written per TiDB node per second. - A value of `0` means there is no limit on the number of slow query log entries written per second. - A value greater than `0` means TiDB writes at most the specified number of slow query log entries per second. Any excess log entries are discarded and not written to the slow query log file. -- This variable is often used with [`tidb_slow_log_rules`](#tidb_slow_log_rules-new-in-v856) to prevent excessive slow query logs from being generated under high-workload conditions. +- 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 New in v8.5.6 and TiDB-X-CLOUD.202603 +### tidb_slow_log_rules New in v8.5.6 and CLOUD.202603.1 {#tidb_slow_log_rule} >**Note:** > @@ -6001,7 +6005,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) > **Tip:** > -> - When enabling `tidb_slow_log_rules` in a production environment, it is recommended to also configure [`tidb_slow_log_max_per_sec`](#tidb_slow_log_max_per_sec-new-in-v856) to avoid excessively frequent slow query log printing. +> - When enabling `tidb_slow_log_rules` in a production environment, it is recommended to also configure [`tidb_slow_log_max_per_sec`](#tidb_slow_log_max_per_sec) to avoid excessively frequent slow query log printing. > - It is recommended to start with stricter conditions and gradually relax them based on troubleshooting needs. For more information on performance impact, see [Recommendations](/config-slow-query-trigger-rules.md#recommendations). From cf782ecec9cd25cd15d6fa4c528592c703f6dde9 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Wed, 9 Sep 2026 12:06:44 +0800 Subject: [PATCH 15/18] Update identify-slow-queries.md --- 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 42654948b17bd..f070a981b93ab 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -174,7 +174,7 @@ Fields related to storage engines: ## Related system variables -* [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules): see [`tidb_slow_log_rules` recommendations](/config-slow-query-trigger-rules.md#recommendations) +* [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules): defines the trigger rules for slow query logs. For more information, see [Configure Trigger Rules for Slow Queries](/config-slow-query-trigger-rules.md). * [`tidb_slow_log_threshold`](/system-variables.md#tidb_slow_log_threshold): sets the threshold for slow query logging. SQL statements whose execution time exceeds this threshold are recorded in the slow query log. The default value is `300ms` (milliseconds). From e33c6ffae120a0668adc1c24263a1878d4d71e3d Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Thu, 10 Sep 2026 23:22:42 +0800 Subject: [PATCH 16/18] Update config-slow-query-trigger-rules.md --- config-slow-query-trigger-rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config-slow-query-trigger-rules.md b/config-slow-query-trigger-rules.md index 37e1843efbdda..5af09b5aa8d16 100644 --- a/config-slow-query-trigger-rules.md +++ b/config-slow-query-trigger-rules.md @@ -19,7 +19,7 @@ For TiDB Self-Managed, the triggering behavior of slow query logs depends on the -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. +In the [TiDB Cloud console](https://tidbcloud.com/), 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. From 0a85eece8501e340b2aeac5b82b1f2f28edf4b06 Mon Sep 17 00:00:00 2001 From: qiancai Date: Thu, 10 Sep 2026 23:33:53 +0800 Subject: [PATCH 17/18] resolve comments from XuHuaiyu --- config-slow-query-trigger-rules.md | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/config-slow-query-trigger-rules.md b/config-slow-query-trigger-rules.md index 5af09b5aa8d16..b40d4ce86db7b 100644 --- a/config-slow-query-trigger-rules.md +++ b/config-slow-query-trigger-rules.md @@ -98,7 +98,7 @@ TiDB Cloud Essential and TiDB Cloud Premium support only `SESSION` rules for `ti - Matching semantics: - - Numeric fields are matched using `>=`. String and boolean fields are matched using equality (`=`). + - Numeric fields except `Conn_ID` are matched using `>=`. `Conn_ID`, string fields, and boolean fields are matched using equality (`=`). - Matching for `DB` and `Resource_group` is case-insensitive. - Explicit operators such as `>`, `<`, and `!=` are not supported. @@ -118,7 +118,7 @@ The fields in the following table follow the general matching and type rules des | 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. | +| `Conn_ID` | `uint` | count | The connection ID (session ID). This field uses exact matching. For example, `Conn_ID:3` matches only logs whose session ID is `3`. This field is supported only in `GLOBAL` rules. | | `Session_alias` | `string` | none | The alias of the current session. | | `DB` | `string` | none | The current database. Matching is case-insensitive. | | `Exec_retry_count` | `uint` | count | The retry times of this statement. This field is usually for pessimistic transactions in which the statement is retried when the lock fails. | @@ -139,14 +139,6 @@ The fields in the following table follow the general matching and type rules des | `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. | -| `Unpacked_bytes_received_tikv_total` | `int` | bytes | The total amount of uncompressed data received from TiKV by this statement. | -| `Unpacked_bytes_sent_tikv_cross_zone` | `int` | bytes | The amount of uncompressed data sent to TiKV across availability zones by this statement. | -| `Unpacked_bytes_received_tikv_cross_zone` | `int` | bytes | The amount of uncompressed data received from TiKV across availability zones by this statement. | -| `Unpacked_bytes_sent_tiflash_total` | `int` | bytes | The total amount of uncompressed data sent to TiFlash by this statement. | -| `Unpacked_bytes_received_tiflash_total` | `int` | bytes | The total amount of uncompressed data received from TiFlash by this statement. | -| `Unpacked_bytes_sent_tiflash_cross_zone` | `int` | bytes | The amount of uncompressed data sent to TiFlash across availability zones by this statement. | -| `Unpacked_bytes_received_tiflash_cross_zone` | `int` | bytes | The amount of uncompressed data received from TiFlash across availability zones by this statement. | | `Process_time` | `float` | second | The total processing time of a SQL statement in TiKV. Because data is sent to TiKV concurrently, this value might exceed `Query_time`. | | `Backoff_time` | `float` | second | The waiting time before retrying when a statement encounters errors that require a retry. Common errors include lock conflicts, Region splits, and busy TiKV servers. | | `Total_keys` | `uint` | count | The number of keys that Coprocessor has scanned. | From eaa4c1e2aba53f0a291cd5aa0230a9e35af82a21 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Thu, 10 Sep 2026 23:35:51 +0800 Subject: [PATCH 18/18] 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 2fb1b6f61c671..a0b7046ec5c24 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5985,7 +5985,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) - A value greater than `0` means TiDB writes at most the specified number of slow query log entries per second. Any excess log entries are discarded and not written to the slow query log file. - 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 New in v8.5.6 and CLOUD.202603.1 {#tidb_slow_log_rule} +### tidb_slow_log_rules New in v8.5.6 and CLOUD.202603.1 {#tidb_slow_log_rules} >**Note:** >