Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
zimulala wants to merge 9 commits into
base: master
Choose a base branch
from
+134 −65
Open

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

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
bb57032
*: update tidb_slow_log_rules
zimulala Feb 9, 2026
77f26db
docs: fix markdownlint list spacing in tidb_slow_log_rules
zimulala Feb 9, 2026
403903b
*: tiny update
zimulala Mar 10, 2026
689378e
Update system-variables.md
zimulala Mar 10, 2026
77eef2f
Add detailed tidb_slow_log_rules usage docs
hfxsd Mar 13, 2026
ebef6b6
Update identify-slow-queries.md
hfxsd Mar 18, 2026
840849c
Update identify-slow-queries.md
hfxsd Mar 18, 2026
822947d
Apply suggestions from code review
lilin90 Mar 30, 2026
0a34162
Update list format
lilin90 Mar 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
195 changes: 131 additions & 64 deletions identify-slow-queries.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -186,80 +186,147 @@ Slow Query 基础信息：
SELECT /*+ WRITE_SLOW_LOG */ count(*) FROM t t1, t t2 WHERE t1.a = t2.b;
```

## `tidb_slow_log_rules` 使用方法

[`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-从-v900-版本开始引入) 用于定义慢查询日志的触发规则，支持多维度指标组合条件。适合用于慢日志的“定向采样”和“问题复现”，可按具体指标组合条件筛选目标语句。

慢查询日志的触发行为取决于 `tidb_slow_log_rules` 的配置情况：

- 如果未设置 `tidb_slow_log_rules`，慢查询日志触发仍依赖 [`tidb_slow_log_threshold`](/system-variables.md#tidb_slow_log_threshold)（单位：毫秒）。
- 如果已设置 `tidb_slow_log_rules`，配置的规则优先生效，[`tidb_slow_log_threshold`](/system-variables.md#tidb_slow_log_threshold) 将被忽略。

如需了解各字段的具体含义、诊断价值和背景信息，请参见[字段含义说明](#字段含义说明)。

### 统一规则语法与类型约束

- 规则容量与分隔：`SESSION` 和 `GLOBAL` 各最多支持 10 条规则，同一会话最多可生效 20 条，规则之间用 `;` 分隔。
- 条件格式：格式为 `字段名:值`，单条规则内的多个条件用 `,` 分隔。
- 字段与作用域：字段名大小写不敏感（需保留下划线等字符）。`SESSION` 规则不支持 `Conn_ID`，仅 `GLOBAL` 支持 `Conn_ID`。
- 匹配语义：
- 数值字段按 `>=` 匹配，字符串和布尔字段按等值匹配（`=`）。
- `DB` 与 `Resource_group` 匹配时不区分大小写。
- 不支持显式操作符（如 `>`, `<`, `!=`）。

类型约束如下：

- 数值类型（`int64`、`uint64`、`float64`）统一要求 `>= 0`，负值会解析报错。
- `int64`：上限 `2^63-1`。
- `uint64`：上限 `2^64-1`。
- `float64`：常规上限约 `1.79e308`。当前按 Go `ParseFloat` 解析，`NaN`/`Inf` 虽可被解析，但可能导致规则恒真或恒假，不建议使用。
- `bool`：支持 `true`/`false`、`1`/`0`、`t`/`f`（大小写不敏感）。
- `string`：当前不支持包含分隔符 `,`（条件分隔符）或 `;`（规则分隔符），即使使用引号（单引号或双引号）也不支持。不支持转义。
- 重复字段：如果在单条规则内多次设置同一字段，以最后一次出现的值为准。

### 支持的字段列表

字段的详细解释、诊断含义和背景信息请参考 [`identify-slow-queries` 的字段含义说明](/identify-slow-queries.md#字段含义说明)。

除特别说明外，下表中的字段默认遵循上文[统一规则语法与类型约束](#统一规则语法与类型约束)中的通用匹配与类型规则。本表仅列出当前支持的字段名、类型、单位以及少量规则侧特殊说明，不重复维护字段语义。

| 字段名 | 类型 | 单位 | 备注 |
| -------------------------------------- | -------- | ------ | ------------------------------ |
| `Conn_ID` | `uint` | 计数 | 仅 GLOBAL 规则支持 |
| `Session_alias` | `string` | 无 | - |
| `DB` | `string` | 无 | 匹配时不区分大小写 |
| `Exec_retry_count` | `uint` | 计数 | - |
| `Query_time` | `float` | 秒 | - |
| `Parse_time` | `float` | 秒 | - |
| `Compile_time` | `float` | 秒 | - |
| `Rewrite_time` | `float` | 秒 | - |
| `Optimize_time` | `float` | 秒 | - |
| `Wait_TS` | `float` | 秒 | - |
| `Is_internal` | `bool` | 无 | - |
| `Digest` | `string` | 无 | - |
| `Plan_digest` | `string` | 无 | - |
| `Num_cop_tasks` | `int` | 计数 | - |
| `Mem_max` | `int` | bytes | - |
| `Disk_max` | `int` | bytes | - |
| `Write_sql_response_total` | `float` | 秒 | - |
| `Succ` | `bool` | 无 | - |
| `Resource_group` | `string` | 无 | 匹配时不区分大小写 |
| `KV_total` | `float` | 秒 | - |
| `PD_total` | `float` | 秒 | - |
| `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` | 秒 | - |
| `Backoff_time` | `float` | 秒 | - |
| `Total_keys` | `uint` | 计数 | - |
| `Process_keys` | `uint` | 计数 | - |
| `cop_mvcc_read_amplification` | `float` | ratio | ratio 值 (Total_keys / Process_keys) |
| `Prewrite_time` | `float` | 秒 | - |
| `Commit_time` | `float` | 秒 | - |
| `Write_keys` | `uint` | 计数 | - |
| `Write_size` | `uint` | bytes | - |
| `Prewrite_region` | `uint` | 计数 | - |

### 生效行为与匹配顺序

- 规则更新行为：每次执行 `SET [SESSION|GLOBAL] tidb_slow_log_rules = '...'` 都会覆盖对应作用域原有规则，不会追加。
- 规则清空行为：`SET [SESSION|GLOBAL] tidb_slow_log_rules = ''` 会清空对应作用域规则。
- 在当前会话存在可生效的 `tidb_slow_log_rules`（如 SESSION 规则、GLOBAL 的当前 `Conn_ID` 规则，或未指定 `Conn_ID` 的全局规则）时，慢查询日志输出由规则匹配结果决定，`tidb_slow_log_threshold` 不再参与判断。
- 在当前会话没有任何可适用规则时，例如 SESSION 和 GLOBAL 都为空，或仅配置了与当前 `Conn_ID` 不匹配的 GLOBAL 规则，慢查询日志触发仍依赖 `tidb_slow_log_threshold`（注意其单位为毫秒）。
- 如果希望规则中仍使用 SQL 执行时间作为输出慢日志的条件，可在规则中使用 `Query_time`（注意其单位为秒）并设置阈值。
- 规则匹配逻辑如下：
- 多条规则之间采用 `OR` 关系，单条规则内多个字段条件采用 `AND` 关系。
- SESSION 作用域规则优先匹配，若未匹配，再按顺序匹配 GLOBAL 的 `Conn_ID` 定向规则和未指定 `Conn_ID` 的全局通用规则。
- `SHOW VARIABLES LIKE 'tidb_slow_log_rules'` 与 `SELECT @@SESSION.tidb_slow_log_rules` 返回 SESSION 规则文本（未设置时为空字符串），`SELECT @@GLOBAL.tidb_slow_log_rules` 返回 GLOBAL 规则文本。

### 使用示例

- 标准格式（SESSION 作用域）：

```sql
SET SESSION tidb_slow_log_rules = 'Query_time: 0.5, Is_internal: false';
```

- 错误格式（SESSION 作用域不支持 `Conn_ID`）：

```sql
SET SESSION tidb_slow_log_rules = 'Conn_ID: 12, Query_time: 0.5, Is_internal: false';
```

- 全局规则（适用于所有连接）：

```sql
SET GLOBAL tidb_slow_log_rules = 'Query_time: 0.5, Is_internal: false';
```

- 指定特定连接的全局规则（分别适用于 `Conn_ID:11` 和 `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';
```

### 使用建议

- `tidb_slow_log_rules` 用于替换单一阈值方式，支持多维度指标组合条件，以实现更灵活和精细化的慢查询日志控制。

- 在资源充足的测试环境（1 个 TiDB 节点，16 核 CPU、48 GiB 内存；3 个 TiKV 节点，每个 16 核 CPU、48 GiB 内存）中，多次 sysbench 测试结果表明：当多维慢查询日志规则在 30 分钟内生成数百万条慢查询日志时，对性能影响较小；但当日志量达到千万级时，TPS 会明显下降，延迟也会显著增加。因此在业务负载较高，或 CPU、内存资源接近瓶颈的情况下，应谨慎配置 `tidb_slow_log_rules`，避免因规则过宽导致日志洪泛。若需要限制日志输出速率，可通过 [`tidb_slow_log_max_per_sec`](#tidb_slow_log_max_per_sec-从-v900-版本开始引入) 进行限速，以降低对业务性能的影响。

## 相关系统变量

* [`tidb_slow_log_threshold`](/system-variables.md#tidb_slow_log_threshold)：用于设置慢查询日志的阈值，执行时间超过阈值的 SQL 语句将被记录到慢查询日志中。默认值是 300 ms。
* [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-从-v900-版本开始引入)：用于定义慢查询日志的触发规则，支持多维度指标组合条件，以实现更加灵活和精细化的日志记录控制。该变量在 v9.0.0 版本中引入，逐步替代传统的单一阈值控制方式，即替代 `tidb_slow_log_threshold` 的使用。该变量支持将以下字段作为筛选条件，设置输出慢查询日志的条件。详情请参考[字段含义说明](#字段含义说明)。
- 支持的筛选字段：
* Slow Query 基础信息：
* `Query_time`、`Parse_time`、`Compile_time`、`Optimize_time`、`Wait_TS`、`Rewrite_time`
* `Digest`、`Plan_digest`、`Is_internal`、`Succ`
* `Exec_retry_count`、`Backoff_time`、`Write_sql_response_total`
* 事务执行相关的字段：
* `Prewrite_time`、`Commit_time`、`Write_keys`、`Write_size`、`Prewrite_region`
* SQL 执行的用户相关的字段：
* `Conn_ID`、`DB`、`Session_alias`
* TiKV Coprocessor Task 相关的字段：
* `Process_time`、`Total_keys`、`Process_keys`、`Num_cop_tasks`
* 内存使用相关的字段：
* `Mem_max`
* 硬盘使用相关的字段：
* `Disk_max`
* 资源管控相关的字段：
* `Resource_group`
* 网络传输相关的字段：
* `KV_total`、`PD_total`
* `Unpacked_bytes_sent_tikv_total`、`Unpacked_bytes_received_tikv_total`
* `Unpacked_bytes_sent_tikv_cross_zone`、`Unpacked_bytes_received_tikv_cross_zone`
* `Unpacked_bytes_sent_tiflash_total`、`Unpacked_bytes_received_tiflash_total`
* `Unpacked_bytes_sent_tiflash_cross_zone`、`Unpacked_bytes_received_tiflash_cross_zone`
* 如果未设置 `tidb_slow_log_rules`：
* 慢查询日志触发仍依赖 `tidb_slow_log_threshold`。注：`query_time` 阈值的含义同该变量，均表示 SQL 执行时长阈值，以保持向后兼容。
* 如果已设置 `tidb_slow_log_rules`：
* 配置的规则优先生效，`tidb_slow_log_threshold` 将被忽略。
* 若希望规则中仍使用 SQL 执行时间作为输出慢日志的条件之一，可在设置规则时使用`query_time` 并设置阈值。
* 规则匹配逻辑（多条规则之间采用 OR 关系）：
* SESSION 作用域规则：优先匹配，如果匹配成功，则打印慢查询日志。
* GLOBAL 作用域规则：仅在 SESSION 作用域规则未匹配时考虑：
* 若规则指定了 `ConnID` 并与当前会话的 `ConnID` 匹配，则使用该规则。
* 若规则未指定 `ConnID`（全局通用规则），则使用该规则。
* 使用 `SHOW VARIABLES`、`SELECT @@GLOBAL.tidb_slow_log_rules`、`SELECT @@SESSION.tidb_slow_log_rules` 显示该变量的行为与其他系统变量一致。
* 使用示例：
* 标准格式（SESSION 作用域）：

```sql
SET SESSION tidb_slow_log_rules = 'Query_time: 500, Is_internal: false';
```

* 错误格式（SESSION 作用域不支持 `ConnID`）：

```sql
SET SESSION tidb_slow_log_rules = 'ConnID: 12, Query_time: 500, Is_internal: false';
```

* 全局规则（适用于所有连接）：

```sql
SET GLOBAL tidb_slow_log_rules = 'Query_time: 500, Is_internal: false';
```

* 指定特定连接的全局规则（分别适用于 `ConnID:11` 和 `ConnID:11` 的两个连接）：

```sql
SET GLOBAL tidb_slow_log_rules = 'ConnID: 11, Query_time: 500, Is_internal: false; ConnID: 12, Query_time: 600, Process_time: 300, DB: db1';
```

> **Tip:**
* [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-从-v900-版本开始引入)：请参见 [`tidb_slow_log_rules` 使用建议](#tidb_slow_log_rules-使用建议)

* [`tidb_slow_log_threshold`](/system-variables.md#tidb_slow_log_threshold)：用于设置慢查询日志的阈值，执行时间超过阈值的 SQL 语句将被记录到慢查询日志中。默认值是 `300ms`（单位：毫秒）。
> **注意：**
>
> - `tidb_slow_log_rules` 用于替换单一阈值的方式，实现更灵活和精细化的慢查询日志控制，支持多维度指标组合条件。
> - 在资源充足的测试环境（1 个 TiDB 节点，16 核 CPU、48 GiB 内存；3 个 TiKV 节点，每个 16 核 CPU、48 GiB 内存）中，多次 sysbench 测试结果表明：当多维慢查询日志规则在 30 分钟内生成数百万条慢查询日志时，对性能影响较小；但当日志量达到千万级时，TPS 会明显下降，延迟也会显著增加。在业务负载较高或 CPU、内存资源接近瓶颈的情况下，应谨慎配置 `tidb_slow_log_rules`，避免因规则过宽导致日志洪泛。建议结合使用 `tidb_slow_log_max_per_sec` 来限制日志打印速率，以降低对业务性能的影响。
> `tidb_slow_log_rules` 中 `Query_time`、`Process_time` 等时间类字段单位为秒（可带小数），而 [`tidb_slow_log_threshold`](/system-variables.md#tidb_slow_log_threshold) 的单位为毫秒。

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

* [`tidb_query_log_max_len`](/system-variables.md#tidb_query_log_max_len)：设置慢查询日志记录 SQL 语句的最大长度。默认值是 4096 byte。

* [`tidb_redact_log`](/system-variables.md#tidb_redact_log)：设置慢查询日志记录 SQL 时，是否将用户数据脱敏用 `?` 代替。默认值是 `0`，即关闭该功能。

* [`tidb_enable_collect_execution_info`](/system-variables.md#tidb_enable_collect_execution_info)：设置是否记录执行计划中各个算子的物理执行信息，默认值是 `1`。开启该功能会导致性能降低约 3%。开启后查看 `Plan` 的示例如下：

```sql
Expand Down
4 changes: 3 additions & 1 deletion system-variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5147,10 +5147,12 @@ Query OK, 0 rows affected, 1 warning (0.00 sec)
- 默认值：""
- 类型：字符串
- 用于定义慢查询日志的触发规则，支持基于多维度指标的组合条件，实现更加灵活和精细化的日志记录控制。
- 关于该系统变量的详细使用方法，请参考 [`tidb_slow_log_rules` 使用方法](/identify-slow-queries.md#tidb_slow_log_rules-使用方法)。

> **Tip:**
>
> 建议在启用 `tidb_slow_log_rules` 后，同时配置 [`tidb_slow_log_max_per_sec`](#tidb_slow_log_max_per_sec-从-v900-版本开始引入)，以限制慢查询日志打印频率，防止基于规则的慢查询日志触发过于频繁。
> - 在生产环境启用 `tidb_slow_log_rules` 时，建议同时配置 [`tidb_slow_log_max_per_sec`](#tidb_slow_log_max_per_sec-从-v900-版本开始引入)，避免慢查询日志打印过于频繁。
> - 规则建议先从较严格条件开始，再按排障需求逐步放宽。更多性能影响介绍，请参考[使用建议](/identify-slow-queries.md#使用建议)。

### `tidb_slow_log_threshold`

Expand Down
Loading