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

Author: jiong-nba

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

@@ -126,13 +126,16 @@ The output is as follows:
 | 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)
 ```
 
 The maximum statement length of the `Query` column is limited by the [`tidb_stmt_summary_max_sql_length`](/system-variables.md#tidb_stmt_summary_max_sql_length-new-in-v40) system variable.
 
+The `Session_connect_attrs` column stores session connection attributes in JSON format parsed from the slow log. TiDB controls the maximum payload size written to this field using [`performance_schema_session_connect_attrs_size`](/system-variables.md#performance_schema_session_connect_attrs_size-new-in-v900).
+
 ## CLUSTER_SLOW_QUERY table
 
 The `CLUSTER_SLOW_QUERY` table provides the slow query information of all nodes in the cluster, which is the parsing result of the TiDB slow log files. You can use the `CLUSTER_SLOW_QUERY` table the way you do with `SLOW_QUERY`. The table schema of the `CLUSTER_SLOW_QUERY` table differs from that of the `SLOW_QUERY` table in that an `INSTANCE` column is added to `CLUSTER_SLOW_QUERY`. The `INSTANCE` column represents the TiDB node address of the row information on the slow query.
@@ -246,9 +249,10 @@ The output is as follows:
 | 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)
 ```
 
 When the cluster system table is queried, TiDB does not obtain data from all nodes, but pushes down the related calculation to other nodes. The execution plan is as follows:

performance-schema/performance-schema-session-connect-attrs.md

@@ -66,3 +66,18 @@ Fields in the `SESSION_CONNECT_ATTRS` table are described as follows:
 * `ATTR_NAME`: Attribute name.
 * `ATTR_VALUE`: Attribute value.
 * `ORDINAL_POSITION`: Ordinal position of the name/value pair.
+
+## Size limit and truncation
+
+TiDB uses the [`performance_schema_session_connect_attrs_size`](/system-variables.md#performance_schema_session_connect_attrs_size-new-in-v900) global system variable to control the maximum total size of connection attributes per session.
+
+- Default value: `4096` bytes
+- Range: `[-1, 65536]`
+- `-1` means no configured limit, and TiDB treats it as up to `65536` bytes.
+- `0` means that TiDB does not retain client-provided session connection attributes, which effectively disables recording session attributes.
+
+When the total size exceeds this limit, TiDB truncates excess attributes and adds `_truncated` to indicate the number of truncated bytes.
+
+The accepted connection attributes are also written to the `Session_connect_attrs` field in the slow log and can be queried from [`INFORMATION_SCHEMA.SLOW_QUERY`](/information-schema/information-schema-slow-query.md) and `INFORMATION_SCHEMA.CLUSTER_SLOW_QUERY`. To control the payload size written to the slow log, adjust `performance_schema_session_connect_attrs_size`.
+
+TiDB also enforces a hard limit of 1 MiB on connection attribute payload in handshake packets. If this hard limit is exceeded, the connection is rejected.

status-variables.md

@@ -31,6 +31,18 @@ Additionally, the [FLUSH STATUS](/sql-statements/sql-statement-flush-status.md)
 - Type: Integer
 - The compression level that is used for the MySQL Protocol.
 
+### Performance_schema_session_connect_attrs_longest_seen
+
+- Scope: GLOBAL
+- Type: Integer
+- The largest total size (in bytes) of session connection attributes observed by TiDB.
+
+### Performance_schema_session_connect_attrs_lost
+
+- Scope: GLOBAL
+- Type: Integer
+- The number of sessions whose connection attributes were truncated due to `performance_schema_session_connect_attrs_size`.
+
 ### Ssl_cipher
 
 - Scope: SESSION | GLOBAL

system-variable-reference.md

@@ -600,6 +600,13 @@ Referenced in:
 - [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
+
+Referenced in:
+
+- [`SESSION_CONNECT_ATTRS`](/performance-schema/performance-schema-session-connect-attrs.md)
+- [System Variables](/system-variables.md#performance_schema_session_connect_attrs_size-new-in-v900)
+
 ### plugin_dir
 
 Referenced in:

system-variables.md

@@ -803,6 +803,26 @@ mysql> SHOW GLOBAL VARIABLES LIKE 'max_prepared_stmt_count';
     * In a cluster with a large number of Regions, the PD leader experiences high CPU pressure due to the increased overhead of handling heartbeats and scheduling tasks.
     * In a TiDB cluster with many TiDB instances, the PD leader experiences high CPU pressure due to a high concurrency of requests for Region information.
 
+### performance_schema_session_connect_attrs_size <span class="version-mark">New in v9.0.0</span>
+
+- Scope: GLOBAL
+- Persists to cluster: Yes
+- Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No
+- Type: Integer
+- Default value: `4096`
+- Range: `[-1, 65536]`
+- Unit: Bytes
+- Controls the maximum total size of connection attributes for each session.
+- If the total size of connection attributes exceeds this value, TiDB truncates excess attributes and adds `_truncated` to indicate the number of truncated bytes.
+- Connection attributes accepted within this limit are written to the `Session_connect_attrs` field in the slow log and can be queried from [`INFORMATION_SCHEMA.SLOW_QUERY`](/information-schema/information-schema-slow-query.md) and `INFORMATION_SCHEMA.CLUSTER_SLOW_QUERY`.
+- You can control the size of `Session_connect_attrs` recorded in the slow log by adjusting this variable.
+- If the value is set to `-1`, this means the limit is not configured and TiDB treats it as up to `65536` bytes.
+- If the value is set to `0`, TiDB does not retain client-provided session connection attributes, which effectively disables recording session attributes.
+
+> **Note:**
+>
+> TiDB enforces a hard limit of 1 MiB for handshake connection attributes. If this hard limit is exceeded, the connection is rejected.
+
 ### plugin_dir
 
 > **Note:**