diff --git a/en_US/admin/cli.md b/en_US/admin/cli.md index fb9ba3a5d..d5d852ab8 100644 --- a/en_US/admin/cli.md +++ b/en_US/admin/cli.md @@ -313,6 +313,46 @@ $ emqx ctl clients kick emqx_c ok ``` +### clients stats --file +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 path/to/file.csv +``` + +**Arguments:** + +- Path to the output CSV file. +- `--batch` option controls how many clients to be processed in one batch. A smaller value reduces resource usage but increases the total execution time. (default is `1000`). +- `--sleep` option controls the pause duration (in milliseconds) between processing batches. Increasing this value can further reduce system impact at the cost of longer execution time. (default is `10ms`). + +**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 received messages (or message fragments) +- `send_oct`: Total bytes sent to the client +- `send_cnt`: Number of sent MQTT packets. +- `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 in-memory session message queue +- `mqueue_dropped`: Number of messages dropped from the in-memory session 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. diff --git a/zh_CN/admin/cli.md b/zh_CN/admin/cli.md index e11135841..04a3b240b 100644 --- a/zh_CN/admin/cli.md +++ b/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 + +将每个客户端的统计信息导出为 CSV 文件,便于系统管理员观察客户端活动,并识别 Top-k 最繁忙的客户端。 + +```bash +$ emqx ctl clients stats --file path/to/file.csv +``` + +**参数说明:** + +- 输出 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`:发送的 MQTT 报文数量 +- `subscriptions_cnt`:客户端持有的订阅数量 +- `awaiting_rel_cnt`:等待 PUBREL 的 QoS 2 消息数量 +- `mqueue_len`:客户端内存会话消息队列的长度 +- `mqueue_dropped`:从客户端内存会话消息队列中被丢弃的消息数量 + +**注意事项:** + +- 该命令用于观测性分析,并非实时遥测工具。 +- 为避免性能下降,命令在扫描 ETS(Erlang Term Storage,Erlang 数据存储)表时会定期休眠(例如每处理 1000 条记录休眠 10 毫秒)。 +- 生成的 CSV 文件可用于离线分析、可视化展示或进一步的自动化处理。 + ## topics 该命令用于查看当前系统中所有订阅的主题。