diff --git a/statement-summary-tables.md b/statement-summary-tables.md index 2a914aa3ddbe..cb0edf62961f 100644 --- a/statement-summary-tables.md +++ b/statement-summary-tables.md @@ -81,6 +81,7 @@ select * from employee where id in (...) and salary between ? and ?; > > - 在 TiDB 中,statement summary tables 中字段的时间单位是纳秒 (ns),而 MySQL 中的时间单位是皮秒 (ps)。 > - 从 v7.5.1 和 v7.6.0 版本开始,对于开启[资源管控](/tidb-resource-control-ru-groups.md)的集群,`statements_summary` 会分资源组进行聚合,即在不同资源组执行的相同语句会被收集为不同的记录。 +> - 从 v8.5.7 开始,你可以通过 [`tidb_stmt_summary_group_by_user`](/system-variables.md#tidb_stmt_summary_group_by_user-从-v857-版本开始引入) 控制是否按执行用户进一步聚合 statement summary。当该变量值为 `ON` 时,不同用户执行的相同 SQL digest 会被收集为不同的记录,每条记录的 `SAMPLE_USER` 字段表示该记录对应的执行用户。 ## `statements_summary_history` @@ -124,6 +125,8 @@ select * from employee where id in (...) and salary between ? and ?; - `tidb_stmt_summary_max_sql_length`:字段 `DIGEST_TEXT` 和 `QUERY_SAMPLE_TEXT` 的最大显示长度,默认值是 4096。 - `tidb_stmt_summary_internal_query`:是否统计 TiDB 的内部 SQL。1 代表统计,0 代表不统计,默认不统计。 +- `tidb_stmt_summary_group_by_user`:是否按执行用户进一步聚合 statement summary。1 代表按用户聚合,0 代表不按用户聚合,默认不按用户聚合。开启后,不同用户执行的相同 SQL digest 会聚合为不同行,可能增加 statement summary 的记录数和内存占用。修改该变量值会清空当前内存中的 statement summary 数据。 +- `tidb_stmt_summary_persist_evicted`:是否在开启 [statement summary 持久化](#持久化-statements-summary)后,将被 LRU 驱逐的 statement summary 记录逐条写入 statement summary 日志。1 代表写入,0 代表不写入,默认不写入。开启后,日志中会出现带有 `"evicted": true` 标记的 JSON 记录,日志量会随 LRU 驱逐频率增加。 statement summary 配置示例如下: @@ -217,6 +220,7 @@ tidb_stmt_summary_enable_persistent = true > > - 当开启持久化后,由于不再于内存中维护历史数据,因此[参数配置](#参数配置)一节所描述的 `tidb_stmt_summary_history_size` 将不再生效,而是由 [`tidb_stmt_summary_file_max_days`](/tidb-configuration-file.md#tidb_stmt_summary_file_max_days-从-v660-版本开始引入)、[`tidb_stmt_summary_file_max_size`](/tidb-configuration-file.md#tidb_stmt_summary_file_max_size-从-v660-版本开始引入) 和 [`tidb_stmt_summary_file_max_backups`](/tidb-configuration-file.md#tidb_stmt_summary_file_max_backups-从-v660-版本开始引入) 这三项配置来决定历史数据在磁盘上的保留数量和时间。 > - `tidb_stmt_summary_refresh_interval` 取值越小,数据写入到磁盘就越实时,但写入磁盘的冗余数据也会随之增多。 +> - 从 v8.5.7 开始,你可以开启 [`tidb_stmt_summary_persist_evicted`](/system-variables.md#tidb_stmt_summary_persist_evicted-从-v857-版本开始引入),将被 LRU 驱逐的记录逐条写入 statement summary 日志。写入的 JSON 记录带有 `"evicted": true` 标记,供下游日志消费者识别,不会作为 `statements_summary_history` 或 `cluster_statements_summary_history` 查询结果返回。 ## 排查示例 diff --git a/system-variable-reference.md b/system-variable-reference.md index f13bf6527b04..44d199f15eb2 100644 --- a/system-variable-reference.md +++ b/system-variable-reference.md @@ -3818,6 +3818,14 @@ summary: 查看 TiDB 所有的系统变量,以及引用这些变量的文档 - [系统变量](/system-variables.md#tidb_stmt_summary_filename-从-v660-版本开始引入) - [TiDB 6.6.0 Release Notes](/releases/release-6.6.0.md) +### tidb_stmt_summary_group_by_user + +引用该变量的文档: + +- [SHOW [GLOBAL|SESSION] VARIABLES](/sql-statements/sql-statement-show-variables.md) +- [Statement Summary Tables](/statement-summary-tables.md) +- [系统变量](/system-variables.md#tidb_stmt_summary_group_by_user-从-v857-版本开始引入) + ### tidb_stmt_summary_history_size 引用该变量的文档: @@ -3856,6 +3864,14 @@ summary: 查看 TiDB 所有的系统变量,以及引用这些变量的文档 - [TiDB 5.0.4 Release Notes](/releases/release-5.0.4.md) - [TiDB 4.0.14 Release Notes](/releases/release-4.0.14.md) +### tidb_stmt_summary_persist_evicted + +引用该变量的文档: + +- [SHOW [GLOBAL|SESSION] VARIABLES](/sql-statements/sql-statement-show-variables.md) +- [Statement Summary Tables](/statement-summary-tables.md) +- [系统变量](/system-variables.md#tidb_stmt_summary_persist_evicted-从-v857-版本开始引入) + ### tidb_stmt_summary_refresh_interval 引用该变量的文档: diff --git a/system-variables.md b/system-variables.md index 040a38a5b0e1..ab5cf4f6c04f 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5494,6 +5494,17 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) - 单位:MiB - 只读变量。表示当开启 [statement summary tables 持久化](/statement-summary-tables.md#持久化-statements-summary)后持久化数据单个文件的大小限制。该变量的值与配置文件中 [`tidb_stmt_summary_file_max_size`](/tidb-configuration-file.md#tidb_stmt_summary_file_max_size-从-v660-版本开始引入) 的取值相同。 +### `tidb_stmt_summary_group_by_user` 从 v8.5.7 版本开始引入 + +- 作用域:GLOBAL +- 是否持久化到集群:是 +- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制:否 +- 类型:布尔型 +- 默认值:`OFF` +- 这个变量用于控制是否将执行 SQL 的用户纳入 [statement summary tables](/statement-summary-tables.md) 的聚合维度。当该变量值为 `OFF` 时,不同用户执行的相同 SQL digest 会聚合到同一行,`SAMPLE_USER` 字段显示其中一个采样用户。当该变量值为 `ON` 时,不同用户执行的相同 SQL digest 会聚合为不同行,每行的 `SAMPLE_USER` 字段表示该行对应的执行用户。 +- 修改该变量值会清空当前内存中的 statement summary 数据,因为修改前后的数据使用了不同的聚合维度。已经持久化到磁盘的历史数据不受影响。 +- 开启该变量后,statement summary 记录数可能随同一 SQL digest 的不同执行用户数量增加,进而增加内存占用。 + ### `tidb_stmt_summary_history_size` 从 v4.0 版本开始引入 - 作用域:GLOBAL @@ -5538,6 +5549,17 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) > > 当启用 [`tidb_stmt_summary_enable_persistent`](/statement-summary-tables.md#持久化-statements-summary) 时,`tidb_stmt_summary_max_stmt_count` 仅限制 [`statements_summary`](/statement-summary-tables.md#statements_summary) 表在内存中可存储的 SQL digest 数量。 +### `tidb_stmt_summary_persist_evicted` 从 v8.5.7 版本开始引入 + +- 作用域:GLOBAL +- 是否持久化到集群:是 +- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制:否 +- 类型:布尔型 +- 默认值:`OFF` +- 这个变量用于控制是否在开启 [statement summary tables 持久化](/statement-summary-tables.md#持久化-statements-summary)后,将被 LRU 驱逐的 statement summary 记录逐条写入 statement summary 日志。写入的 JSON 记录会带有 `"evicted": true` 标记,便于下游日志消费者识别这些记录。 +- 该变量仅对持久化的 statement summary 实现生效。`"evicted": true` 的记录不会作为 `statements_summary_history` 或 `cluster_statements_summary_history` 查询结果返回。 +- 开启该变量会使 statement summary 日志量随 LRU 驱逐频率增加。驱逐记录写入采用异步缓冲机制;当缓冲队列已满时,新的驱逐记录可能被丢弃。 + ### `tidb_stmt_summary_refresh_interval` 从 v4.0 版本开始引入 - 作用域:GLOBAL