docs: support logging session connect attrs to slow query log (#21468)

Author: hfxsd

information-schema/information-schema-slow-query.md

@@ -106,13 +106,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    |       |
 +--------------------------------------------+-----------------+------+------+---------+-------+
-89 rows in set (0.00 sec)
+90 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-从-v900-版本开始引入) 系统变量来控制写入此字段的最大负载大小。
+
 ## CLUSTER_SLOW_QUERY table
 
 `CLUSTER_SLOW_QUERY` 表中提供了集群所有节点的慢查询相关的信息，其内容通过解析 TiDB 慢查询日志而来，该表使用上和 `SLOW_QUERY` 表一样。`CLUSTER_SLOW_QUERY` 表结构上比 `SLOW_QUERY` 多一列 `INSTANCE`，表示该行慢查询信息来自的 TiDB 节点地址。关于如何使用该表调查和改善慢查询，请参考[慢查询日志文档](/identify-slow-queries.md)。
@@ -216,9 +219,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    |       |
 +--------------------------------------------+-----------------+------+------+---------+-------+
-90 rows in set (0.00 sec)
+91 rows in set (0.00 sec)
 ```
 
 查询集群系统表时，TiDB 也会将相关计算下推给其他节点执行，而不是把所有节点的数据都取回来，可以查看执行计划，如下：

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-从-v900-版本开始引入) 来控制每个会话连接属性的最大总大小。
+
+- 默认值：`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 的硬性限制。若超过该硬性限制，连接将被拒绝。

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

system-variable-reference.md

@@ -595,6 +595,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-从-v900-版本开始引入)
+
 ### plugin_dir
 
 引用该变量的文档：

system-variables.md

@@ -741,6 +741,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">从 v9.0.0 版本开始引入</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