update(CLI): Add ctl command to dump client stats

en_US/admin/cli.md

@@ -313,6 +313,44 @@ $ emqx ctl clients kick emqx_c
 ok
 ```
 
+### clients stats --file <path/to/file.csv>
+Dumps per-client statistics to a CSV file, allowing system administrators to observe client activity and identify top-k busy clients.
+
+```bash
+$ emqx ctl clients stats --file /var/log/emqx/client_stats_20251020.csv
+```
+
+**Arguments:**
+
+- `--file`: Path to the output CSV file.
+
+**Output Format:**
+
+The generated CSV file will contain the following columns:
+
+```sql
+timestamp, clientid, recv_oct, recv_cnt, send_oct, send_cnt, subscriptions_cnt, awaiting_rel_cnt, mqueue_len, mqueue_dropped
+```
+
+Descriptions of each field:
+
+- `timestamp`: UNIX timestamp in milliseconds when the data was collected
+- `clientid`: MQTT client ID
+- `recv_oct`: Total bytes received from the client
+- `recv_cnt`: Number of receive operations
+- `send_oct`: Total bytes sent to the client
+- `send_cnt`: Number of send operations
+- `subscriptions_cnt`: Number of subscriptions held by the client
+- `awaiting_rel_cnt`: Number of QoS 2 messages awaiting PUBREL
+- `mqueue_len`: Length of the client’s message queue
+- `mqueue_dropped`: Number of messages dropped from the message queue
+
+**Notes:**
+
+- The command is designed for observability, not real-time telemetry.
+- To avoid performance degradation, it throttles Erlang Term Storage (ETS) scans by sleeping periodically (e.g., 10ms every 1000 records).
+- The resulting CSV can be used for offline analysis, visualizations, or further automated processing.
+
 ## topics
 
 This command is to view all subscribed topics in current system.

zh_CN/admin/cli.md

@@ -280,7 +280,7 @@ Automatic cluster discovery enabled.
 
 查看当前连接到 EMQX 的所有客户端。此命令可用于监控活跃客户端及连接数量。
 
-:::tip 提示
+::: tip 提示
 
 如果系统中连接了大量客户端，执行 `list` 命令可能会耗费较多时间和资源。
 
@@ -310,6 +310,45 @@ $ emqx ctl clients kick emqx_c
 ok
 ```
 
+### clients stats --file <path/to/file.csv>
+
+将每个客户端的统计信息导出为 CSV 文件，便于系统管理员观察客户端活动，并识别 Top-k 最繁忙的客户端。
+
+```bash
+$ emqx ctl clients stats --file /var/log/emqx/client_stats_20251020.csv
+```
+
+**参数说明：**
+
+- `--file`：输出 CSV 文件的路径。
+
+**输出格式：**
+
+生成的 CSV 文件将包含以下列：
+
+```sql
+timestamp, clientid, recv_oct, recv_cnt, send_oct, send_cnt, subscriptions_cnt, awaiting_rel_cnt, mqueue_len, mqueue_dropped
+```
+
+各字段含义如下：
+
+- `timestamp`：数据采集时的 UNIX 时间戳（毫秒）
+- `clientid`：MQTT 客户端 ID
+- `recv_oct`：客户端接收的总字节数
+- `recv_cnt`：接收操作的次数
+- `send_oct`：发送给客户端的总字节数
+- `send_cnt`：发送操作的次数
+- `subscriptions_cnt`：客户端当前的订阅数量
+- `awaiting_rel_cnt`：等待 PUBREL 的 QoS 2 消息数量
+- `mqueue_len`：客户端消息队列长度
+- `mqueue_dropped`：客户端消息队列中被丢弃的消息数量
+
+**注意事项：**
+
+- 该命令用于观测性分析，并非实时遥测工具。
+- 为避免性能下降，命令在扫描 ETS（Erlang Term Storage，Erlang 数据存储）表时会定期休眠（例如每处理 1000 条记录休眠 10 毫秒）。
+- 生成的 CSV 文件可用于离线分析、可视化展示或进一步的自动化处理。
+
 ## topics
 
 该命令用于查看当前系统中所有订阅的主题。