pingcap · ti-chi-bot · Mar 30, 2026 · Apr 20, 2026 · Apr 20, 2026 · Apr 20, 2026
diff --git a/information-schema/information-schema-slow-query.md b/information-schema/information-schema-slow-query.md
@@ -98,13 +98,16 @@ DESC slow_query;
 | Plan_digest                   | varchar(128)        | YES  |      | NULL    |       |
 | Binary_plan                   | longtext            | YES  |      | NULL    |       |
 | Prev_stmt                     | longtext            | YES  |      | NULL    |       |
+| Session_connect_attrs         | json                | YES  |      | NULL    |       |
 | Query                         | longtext            | YES  |      | NULL    |       |
 +-------------------------------+---------------------+------+------+---------+-------+
-81 rows in set (0.00 sec)
+82 rows in set (0.00 sec)
 ```
 
 `Query` 列的语句长度上限由系统变量 [`tidb_stmt_summary_max_sql_length`](/system-variables.md#tidb_stmt_summary_max_sql_length-从-v40-版本开始引入) 控制。
 
+`Session_connect_attrs` 列以 JSON 格式存储从慢日志解析出的会话连接属性。TiDB 通过 [`performance_schema_session_connect_attrs_size`](/system-variables.md#performance_schema_session_connect_attrs_size-从-v857-版本开始引入) 系统变量来控制写入此字段的最大负载大小。
+
 ## CLUSTER_SLOW_QUERY table
 
 `CLUSTER_SLOW_QUERY` 表中提供了集群所有节点的慢查询相关的信息，其内容通过解析 TiDB 慢查询日志而来，该表使用上和 `SLOW_QUERY` 表一样。`CLUSTER_SLOW_QUERY` 表结构上比 `SLOW_QUERY` 多一列 `INSTANCE`，表示该行慢查询信息来自的 TiDB 节点地址。关于如何使用该表调查和改善慢查询，请参考[慢查询日志文档](/identify-slow-queries.md)。
@@ -200,9 +203,10 @@ DESC CLUSTER_SLOW_QUERY;
 | Plan_digest                   | varchar(128)        | YES  |      | NULL    |       |
 | Binary_plan                   | longtext            | YES  |      | NULL    |       |
 | Prev_stmt                     | longtext            | YES  |      | NULL    |       |
+| Session_connect_attrs         | json                | YES  |      | NULL    |       |
 | Query                         | longtext            | YES  |      | NULL    |       |
 +-------------------------------+---------------------+------+------+---------+-------+
-82 rows in set (0.00 sec)
+83 rows in set (0.00 sec)
 ```
 
 查询集群系统表时，TiDB 也会将相关计算下推给其他节点执行，而不是把所有节点的数据都取回来，可以查看执行计划，如下：

diff --git a/performance-schema/performance-schema-session-connect-attrs.md b/performance-schema/performance-schema-session-connect-attrs.md
@@ -62,3 +62,18 @@ TABLE SESSION_CONNECT_ATTRS;
 * `ATTR_NAME`：属性名。
 * `ATTR_VALUE`：属性值。
 * `ORDINAL_POSITION`：属性名/属性值对的序号。
+
+## 大小限制与截断
+
+TiDB 使用全局系统变量 [`performance_schema_session_connect_attrs_size`](/system-variables.md#performance_schema_session_connect_attrs_size-从-v857-版本开始引入) 来控制每个会话连接属性的最大总大小。
+
+- 默认值：`4096` 字节
+- 取值范围：`[-1, 65536]`
+- `-1` 表示不配置限制，TiDB 会将其视为最大 `65536` 字节。
+- `0` 表示 TiDB 不会保留客户端提供的会话连接属性，禁用会话属性记录。
+
+当总大小超过该限制时，TiDB 会截断超出的属性，并添加 `_truncated` 来表示被截断的字节数。
+
+已接受的连接属性也会写入慢日志中的 `Session_connect_attrs` 字段，并可通过 [`INFORMATION_SCHEMA.SLOW_QUERY`](/information-schema/information-schema-slow-query.md) 和 `INFORMATION_SCHEMA.CLUSTER_SLOW_QUERY` 查询。若要控制写入慢日志的负载大小，可调整 `performance_schema_session_connect_attrs_size`。
+
+此外，TiDB 还会对握手包中的连接属性负载强制施加 1 MiB 的硬性限制。若超过该硬性限制，连接将被拒绝。
diff --git a/status-variables.md b/status-variables.md
@@ -31,6 +31,18 @@ summary: 使用状态变量查看系统和会话状态。
 - 类型：整数型
 - MySQL 协议使用的压缩等级。
 
+### Performance_schema_session_connect_attrs_longest_seen
+
+- 作用域：GLOBAL
+- 类型：整数型
+- TiDB 观测到的会话连接属性的最大总大小（单位为字节 bytes）。
+
+### Performance_schema_session_connect_attrs_lost
+
+- 作用域：GLOBAL
+- 类型：整数型
+- 由于 `performance_schema_session_connect_attrs_size` 而导致连接属性被截断的会话数量。
+
 ### Ssl_cipher
 
 - 作用域：SESSION | GLOBAL

diff --git a/system-variable-reference.md b/system-variable-reference.md
@@ -589,6 +589,13 @@ summary: 查看 TiDB 所有的系统变量，以及引用这些变量的文档
 - [TiDB 8.5.0 Release Notes](/releases/release-8.5.0.md)
 - [TiDB 7.6.0 Release Notes](/releases/release-7.6.0.md)
 
+### performance_schema_session_connect_attrs_size
+
+引用该变量的文档：
+
+- [`SESSION_CONNECT_ATTRS`](/performance-schema/performance-schema-session-connect-attrs.md)
+- [System Variables](/system-variables.md#performance_schema_session_connect_attrs_size-从-v857-版本开始引入)
+
 ### plugin_dir
 
 引用该变量的文档：

diff --git a/system-variables.md b/system-variables.md
@@ -731,6 +731,26 @@ mysql> SHOW GLOBAL VARIABLES LIKE 'max_prepared_stmt_count';
     - 集群 Region 数量较多，PD leader 由于处理心跳和调度任务的开销大，导致 CPU 资源紧张。
     - 集群中 TiDB 实例数量较多，Region 信息请求并发量较大，PD leader CPU 压力大。
 
+### `performance_schema_session_connect_attrs_size` <span class="version-mark">从 v8.5.7 版本开始引入</span>
+
+- 作用域：GLOBAL
+- 是否持久化到集群：是
+- 是否适用于 Hint [`SET_VAR`](/optimizer-hints.md#set_varvar_namevar_value)：否
+- 类型：整数型
+- 默认值：`4096`
+- 取值范围：`[-1, 65536]`
+- 单位：Bytes
+- 控制每个会话连接属性的最大总大小。
+- 如果连接属性的总大小超过此值，TiDB 会截断超出的属性，并添加 `_truncated` 来表示被截断的字节数。
+- 在此限制内被接受的连接属性会写入慢日志中的 `Session_connect_attrs` 字段，并可通过 [`INFORMATION_SCHEMA.SLOW_QUERY`](/information-schema/information-schema-slow-query.md) 和 `INFORMATION_SCHEMA.CLUSTER_SLOW_QUERY` 查询。
+- 你可以通过调整此变量来控制慢日志中记录的 `Session_connect_attrs` 大小。
+- 如果该值设置为 `-1`，表示未配置限制，TiDB 会将其视为最大 `65536` 字节。
+- 如果该值设置为 `0`，TiDB 不会保留客户端提供的会话连接属性，这实际上会禁用会话属性记录。
+
+> **注意：**
+>
+> TiDB 对握手连接属性强制施加 1 MiB 的硬性限制。若超过该硬性限制，连接将被拒绝。
+
 ### `plugin_dir`
 
 - 作用域：GLOBAL