From a61c56b7229ab6c82811e3eaebd35646cfd8e422 Mon Sep 17 00:00:00 2001 From: Meggielqk <126552073+Meggielqk@users.noreply.github.com> Date: Mon, 20 Oct 2025 16:31:13 +0800 Subject: [PATCH 1/5] update(CLI): Add ctl command to dump client stats https://emqx.atlassian.net/browse/EMQX-14624 --- en_US/admin/cli.md | 39 +++++++++++++++++++++++++++++++++++++++ zh_CN/admin/cli.md | 41 ++++++++++++++++++++++++++++++++++++++++- 2 files changed, 79 insertions(+), 1 deletion(-) diff --git a/en_US/admin/cli.md b/en_US/admin/cli.md index fb9ba3a5d..007754c86 100644 --- a/en_US/admin/cli.md +++ b/en_US/admin/cli.md @@ -313,6 +313,45 @@ $ 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 --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. diff --git a/zh_CN/admin/cli.md b/zh_CN/admin/cli.md index e11135841..5f46b3972 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 /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 该命令用于查看当前系统中所有订阅的主题。 From d2f91e795e8a2a62a64a86130c85df23b8ed46e9 Mon Sep 17 00:00:00 2001 From: Meggielqk <126552073+Meggielqk@users.noreply.github.com> Date: Mon, 20 Oct 2025 16:32:43 +0800 Subject: [PATCH 2/5] Update en_US/admin/cli.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- en_US/admin/cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en_US/admin/cli.md b/en_US/admin/cli.md index 007754c86..cb4578e65 100644 --- a/en_US/admin/cli.md +++ b/en_US/admin/cli.md @@ -313,7 +313,7 @@ $ emqx ctl clients kick emqx_c ok ``` -### clients stats -- file +### clients stats -- file Dumps per-client statistics to a CSV file, allowing system administrators to observe client activity and identify top-k busy clients. From 88f657e2c7ff962bf1c4f63c1e52a955c2c8ae59 Mon Sep 17 00:00:00 2001 From: Meggielqk <126552073+Meggielqk@users.noreply.github.com> Date: Mon, 20 Oct 2025 16:34:16 +0800 Subject: [PATCH 3/5] Update cli.md --- en_US/admin/cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en_US/admin/cli.md b/en_US/admin/cli.md index 007754c86..49e063466 100644 --- a/en_US/admin/cli.md +++ b/en_US/admin/cli.md @@ -313,7 +313,7 @@ $ emqx ctl clients kick emqx_c ok ``` -### clients stats -- file +### clients stats --file Dumps per-client statistics to a CSV file, allowing system administrators to observe client activity and identify top-k busy clients. From c9e8e44bb6dbeac8b3d847a31fa15d1b58d09e6d Mon Sep 17 00:00:00 2001 From: Meggielqk <126552073+Meggielqk@users.noreply.github.com> Date: Mon, 20 Oct 2025 16:58:37 +0800 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: zmstone --- en_US/admin/cli.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/en_US/admin/cli.md b/en_US/admin/cli.md index 9f00f8a95..80ca0d602 100644 --- a/en_US/admin/cli.md +++ b/en_US/admin/cli.md @@ -317,12 +317,15 @@ ok 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 +$ emqx ctl clients stats path/to/file.csv ``` **Arguments:** -- `--file`: Path to the output CSV file. +- Path to the output CSV file. +- `--batch` option controls how many clients to be processed in one batch, lower the size will make the command take longer time, but more resource friendly (default is `1000`). +- `--sleep` option controls the number of milliseconds to pause between the chunks, increase it will make the command take longer time, but more resource friendly (default is `10ms`). +- **Output Format:** @@ -337,13 +340,13 @@ 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 +- `recv_cnt`: Number of received messages (or message fragments) - `send_oct`: Total bytes sent to the client -- `send_cnt`: Number of send operations +- `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 message queue -- `mqueue_dropped`: Number of messages dropped from the message queue +- `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:** From 3402ecb3d7af3c104db1cdb0b2db909175ebb2cc Mon Sep 17 00:00:00 2001 From: Meggielqk <126552073+Meggielqk@users.noreply.github.com> Date: Mon, 20 Oct 2025 17:09:30 +0800 Subject: [PATCH 5/5] Update zh descriptions based on comments --- en_US/admin/cli.md | 5 ++--- zh_CN/admin/cli.md | 14 +++++++------- 2 files changed, 9 insertions(+), 10 deletions(-) diff --git a/en_US/admin/cli.md b/en_US/admin/cli.md index 80ca0d602..d5d852ab8 100644 --- a/en_US/admin/cli.md +++ b/en_US/admin/cli.md @@ -323,9 +323,8 @@ $ 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, lower the size will make the command take longer time, but more resource friendly (default is `1000`). -- `--sleep` option controls the number of milliseconds to pause between the chunks, increase it will make the command take longer time, but more resource friendly (default is `10ms`). -- +- `--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:** diff --git a/zh_CN/admin/cli.md b/zh_CN/admin/cli.md index 5f46b3972..04a3b240b 100644 --- a/zh_CN/admin/cli.md +++ b/zh_CN/admin/cli.md @@ -315,12 +315,12 @@ ok 将每个客户端的统计信息导出为 CSV 文件，便于系统管理员观察客户端活动，并识别 Top-k 最繁忙的客户端。 ```bash -$ emqx ctl clients stats --file /var/log/emqx/client_stats_20251020.csv +$ emqx ctl clients stats --file path/to/file.csv ``` **参数说明：** -- `--file`：输出 CSV 文件的路径。 +- 输出 CSV 文件的路径。 **输出格式：** @@ -335,13 +335,13 @@ timestamp, clientid, recv_oct, recv_cnt, send_oct, send_cnt, subscriptions_cnt, - `timestamp`：数据采集时的 UNIX 时间戳（毫秒） - `clientid`：MQTT 客户端 ID - `recv_oct`：客户端接收的总字节数 -- `recv_cnt`：接收操作的次数 +- `recv_cnt`：接收到的消息数量（或消息片段） - `send_oct`：发送给客户端的总字节数 -- `send_cnt`：发送操作的次数 -- `subscriptions_cnt`：客户端当前的订阅数量 +- `send_cnt`：发送的 MQTT 报文数量 +- `subscriptions_cnt`：客户端持有的订阅数量 - `awaiting_rel_cnt`：等待 PUBREL 的 QoS 2 消息数量 -- `mqueue_len`：客户端消息队列长度 -- `mqueue_dropped`：客户端消息队列中被丢弃的消息数量 +- `mqueue_len`：客户端内存会话消息队列的长度 +- `mqueue_dropped`：从客户端内存会话消息队列中被丢弃的消息数量 **注意事项：**