Skip to content

Commit e7f6225

Browse files
hfxsdti-chi-bot
hfxsd
authored and
ti-chi-bot
committed
This is an automated cherry-pick of pingcap#22567
Signed-off-by: ti-chi-bot <ti-community-prow-bot@tidb.io>
1 parent c59faf0 commit e7f6225

2 files changed

Lines changed: 175 additions & 0 deletions

File tree

‎identify-slow-queries.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -172,12 +172,156 @@ Fields related to storage engines:
172172
- `Storage_from_kv`: introduced in v8.5.5, indicates whether this statement read data from TiKV.
173173
- `Storage_from_mpp`: introduced in v8.5.5, indicates whether this statement read data from TiFlash.
174174

175+
## Use `tidb_slow_log_rules`
176+
177+
[`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-new-in-v900) 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.
178+
179+
The triggering behavior of slow query logs depends on the configuration of `tidb_slow_log_rules`:
180+
181+
- 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).
182+
- 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.
183+
184+
For more information about meanings, diagnostic value, and background information of each field, see the [Fields description](#fields-description).
185+
186+
### Unified rule syntax and type constraints
187+
188+
- 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 `;`.
189+
- Condition format: each condition uses the format `field_name:value`. Multiple conditions within a single rule are separated by `,`.
190+
- 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`.
191+
- Matching semantics:
192+
- Numeric fields are matched using `>=`. String and boolean fields are matched using equality (`=`).
193+
- Matching for `DB` and `Resource_group` is case-insensitive.
194+
- Explicit operators such as `>`, `<`, and `!=` are not supported.
195+
196+
Type constraints are as follows:
197+
198+
- Numeric types (`int64`, `uint64`, `float64`) uniformly require `>= 0`. Negative values will result in a parsing error.
199+
- `int64`: the maximum value is `2^63-1`.
200+
- `uint64`: the maximum value is `2^64-1`.
201+
- `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.
202+
- `bool`: supports `true`/`false`, `1`/`0`, and `t`/`f` (case-insensitive).
203+
- `string`: currently does not support strings containing the separators `,` (condition separator) or `;` (rule separator), even with quotes (single or double). Escaping is not supported.
204+
- Duplicate fields: if the same field is specified multiple times in a single rule, the last occurrence takes effect.
205+
206+
### Supported fields
207+
208+
For detailed field descriptions, diagnostic meanings, and background information, see the [field descriptions in `identify-slow-queries`](/identify-slow-queries.md#fields-description).
209+
210+
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.
211+
212+
| Field name | Type | Unit | Notes |
213+
| -------------------------------------- | -------- | ------ | ------------------------------ |
214+
| `Conn_ID` | `uint` | count | Supported only in `GLOBAL` rules |
215+
| `Session_alias` | `string` | none | - |
216+
| `DB` | `string` | none | Case-insensitive when matched |
217+
| `Exec_retry_count` | `uint` | count | - |
218+
| `Query_time` | `float` | second | - |
219+
| `Parse_time` | `float` | second | - |
220+
| `Compile_time` | `float` | second | - |
221+
| `Rewrite_time` | `float` | second | - |
222+
| `Optimize_time` | `float` | second | - |
223+
| `Wait_TS` | `float` | second | - |
224+
| `Is_internal` | `bool` | none | - |
225+
| `Digest` | `string` | none | - |
226+
| `Plan_digest` | `string` | none | - |
227+
| `Num_cop_tasks` | `int` | count | - |
228+
| `Mem_max` | `int` | bytes | - |
229+
| `Disk_max` | `int` | bytes | - |
230+
| `Write_sql_response_total` | `float` | second | - |
231+
| `Succ` | `bool` | none | - |
232+
| `Resource_group` | `string` | none | Case-insensitive when matched |
233+
| `KV_total` | `float` | second | - |
234+
| `PD_total` | `float` | second | - |
235+
| `Unpacked_bytes_sent_tikv_total` | `int` | bytes | - |
236+
| `Unpacked_bytes_received_tikv_total` | `int` | bytes | - |
237+
| `Unpacked_bytes_sent_tikv_cross_zone` | `int` | bytes | - |
238+
| `Unpacked_bytes_received_tikv_cross_zone` | `int` | bytes | - |
239+
| `Unpacked_bytes_sent_tiflash_total` | `int` | bytes | - |
240+
| `Unpacked_bytes_received_tiflash_total` | `int` | bytes | - |
241+
| `Unpacked_bytes_sent_tiflash_cross_zone` | `int` | bytes | - |
242+
| `Unpacked_bytes_received_tiflash_cross_zone` | `int` | bytes | - |
243+
| `Process_time` | `float` | second | - |
244+
| `Backoff_time` | `float` | second | - |
245+
| `Total_keys` | `uint` | count | - |
246+
| `Process_keys` | `uint` | count | - |
247+
| `cop_mvcc_read_amplification` | `float` | ratio | Ratio value (`Total_keys / Process_keys`) |
248+
| `Prewrite_time` | `float` | second | - |
249+
| `Commit_time` | `float` | second | - |
250+
| `Write_keys` | `uint` | count | - |
251+
| `Write_size` | `uint` | bytes | - |
252+
| `Prewrite_region` | `uint` | count | - |
253+
254+
### Effective behavior and matching order
255+
256+
- 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.
257+
- Rule clearing behavior: `SET [SESSION|GLOBAL] tidb_slow_log_rules = ''` clears the rules in the corresponding scope.
258+
- 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.
259+
- 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.
260+
- 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.
261+
- Rule matching logic:
262+
- Multiple rules are combined with `OR`, while multiple field conditions within a single rule are combined with `AND`.
263+
- `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`.
264+
- `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.
265+
266+
### Examples
267+
268+
- Standard format (`SESSION` scope):
269+
270+
```sql
271+
SET SESSION tidb_slow_log_rules = 'Query_time: 0.5, Is_internal: false';
272+
```
273+
274+
- Invalid format (`SESSION` scope does not support `Conn_ID`):
275+
276+
```sql
277+
SET SESSION tidb_slow_log_rules = 'Conn_ID: 12, Query_time: 0.5, Is_internal: false';
278+
```
279+
280+
- Global rule (applies to all connections):
281+
282+
```sql
283+
SET GLOBAL tidb_slow_log_rules = 'Query_time: 0.5, Is_internal: false';
284+
```
285+
286+
- Global rules for specific connections (applied separately to the two connections `Conn_ID:11` and `Conn_ID:12`):
287+
288+
```sql
289+
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';
290+
```
291+
292+
### Recommendations
293+
294+
- `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.
295+
296+
- 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-v900) to throttle it and reduce the impact on business performance.
297+
175298
## Related system variables
176299

300+
<<<<<<< HEAD
177301
* [`tidb_slow_log_threshold`](/system-variables.md#tidb_slow_log_threshold): Sets the threshold for the slow log. The SQL statement whose execution time exceeds this threshold is recorded in the slow log. The default value is 300 (ms).
178302
* [`tidb_query_log_max_len`](/system-variables.md#tidb_query_log_max_len): Sets the maximum length of the SQL statement recorded in the slow log. The default value is 4096 (byte).
179303
* [tidb_redact_log](/system-variables.md#tidb_redact_log): Determines whether to desensitize user data using `?` in the SQL statement recorded in the slow log. The default value is `0`, which means to disable the feature.
180304
* [`tidb_enable_collect_execution_info`](/system-variables.md#tidb_enable_collect_execution_info): Determines whether to record the physical execution information of each operator in the execution plan. The default value is `1`. This feature impacts the performance by approximately 3%. After enabling this feature, you can view the `Plan` information as follows:
305+
=======
306+
* [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-new-in-v900): see [`tidb_slow_log_rules` recommendations](#recommendations)
307+
308+
* [`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).
309+
310+
> **Tip:**
311+
>
312+
> 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.
313+
314+
* [`tidb_slow_log_max_per_sec`](/system-variables.md#tidb_slow_log_max_per_sec-new-in-v900): 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 v9.0.0.
315+
* A value of `0` means there is no limit on the number of slow query log entries written per second.
316+
* 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.
317+
* 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.
318+
319+
* [`tidb_query_log_max_len`](/system-variables.md#tidb_query_log_max_len): sets the maximum length of the SQL statement recorded in the slow query log. The default value is 4096 (byte).
320+
321+
* [`tidb_redact_log`](/system-variables.md#tidb_redact_log): controls whether user data in SQL statements recorded in the slow query log is redacted and replaced with `?`. The default value is `0`, which means this feature is disabled.
322+
323+
* [`tidb_enable_collect_execution_info`](/system-variables.md#tidb_enable_collect_execution_info): controls whether to record the physical execution information of each operator in the execution plan. The default value is `1`. This feature impacts the performance by approximately 3%. After enabling this feature, you can view the `Plan` information as follows:
324+
>>>>>>> 6d6ae318cc (sys-var: clarify `tidb_slow_log_rules` syntax/behavior and de-duplicate slow log docs (#22567))
181325

182326
```sql
183327
> select tidb_decode_plan('jAOIMAk1XzE3CTAJMQlmdW5jczpjb3VudChDb2x1bW4jNyktPkMJC/BMNQkxCXRpbWU6MTAuOTMxNTA1bXMsIGxvb3BzOjIJMzcyIEJ5dGVzCU4vQQoxCTMyXzE4CTAJMQlpbmRleDpTdHJlYW1BZ2dfOQkxCXQRSAwyNzY4LkgALCwgcnBjIG51bTogMQkMEXMQODg0MzUFK0hwcm9jIGtleXM6MjUwMDcJMjA2HXsIMgk1BWM2zwAAMRnIADcVyAAxHcEQNQlOL0EBBPBbCjMJMTNfMTYJMQkzMTI4MS44NTc4MTk5MDUyMTcJdGFibGU6dCwgaW5kZXg6aWR4KGEpLCByYW5nZTpbLWluZiw1MDAwMCksIGtlZXAgb3JkZXI6ZmFsc2UJMjUBrgnQVnsA');

‎system-variables.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5805,6 +5805,37 @@ Query OK, 0 rows affected, 1 warning (0.00 sec)
58055805
>
58065806
> 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.
58075807
5808+
<<<<<<< HEAD
5809+
=======
5810+
### tidb_slow_log_max_per_sec <span class="version-mark">New in v9.0.0</span>
5811+
5812+
- Scope: GLOBAL
5813+
- Persists to cluster: Yes
5814+
- Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No
5815+
- Default value: `0`
5816+
- Type: Integer
5817+
- Range: `[0, 1000000]`
5818+
- This variable controls the maximum number of slow query log entries that can be written per TiDB node per second.
5819+
- A value of `0` means there is no limit on the number of slow query log entries written per second.
5820+
- 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.
5821+
- This variable is often used with [`tidb_slow_log_rules`](#tidb_slow_log_rules-new-in-v900) to prevent excessive slow query logs from being generated under high-workload conditions.
5822+
5823+
### tidb_slow_log_rules <span class="version-mark">New in v9.0.0</span>
5824+
5825+
- Scope: SESSION | GLOBAL
5826+
- Persists to cluster: Yes
5827+
- Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No
5828+
- Default value: ""
5829+
- Type: String
5830+
- This variable defines the triggering rules for slow query logs. It supports combining multi-dimensional metrics to provide more flexible and fine-grained logging.
5831+
- 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).
5832+
5833+
> **Tip:**
5834+
>
5835+
> - 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-v900) to avoid excessively frequent slow query log printing.
5836+
> - 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).
5837+
5838+
>>>>>>> 6d6ae318cc (sys-var: clarify `tidb_slow_log_rules` syntax/behavior and de-duplicate slow log docs (#22567))
58085839
### tidb_slow_log_threshold
58095840
58105841
> **Note:**

0 commit comments

Comments
 (0)