高级进阶

MQTT 5

Clean Start 和会话过期间隔

MQTT 5.0 引入了 Clean Start 和会话过期间隔(Session Expiry Interval)这两项特性,相比于 MQTT 3.1.1 的清除会话(Clean Session)提供了更多的灵活性。

在 MQTTX 中使用时,如果设置了 Clean Start,为了使其生效,需要设定会话过期间隔。默认情况下,如果关闭了 Clean Start,那么会话过期间隔默认设置为 7200 秒(两小时)。如果需要设置为永不过期,可以点击输入框右边的清除按钮,清空值后会话将永不过期。然而,如果关闭会话过期间隔,MQTTX 会自动将会话过期间隔设置为 0,即连接一旦断开,会话立即结束。

mqttx-user-properties-connect

用户属性

点击新建按钮来到新建客户端页面,首先我们需要选择 MQTT 的版本为 5.0。这样,下方就会出现配置用户属性的卡片。卡片内包含一个可配置键值对的输入框。您可以点击右上角的添加按钮来增加用户属性配置,也可以点击每一行末尾的删除按钮删除配置。最后输入需要配置的属性名称和内容即可。连接成功后,MQTT 服务器就能获取到该客户端的用户属性内容。

mqttx-user-properties-connect

除了在客户端连接时配置用户属性外,该版本还支持在发布消息时配置用户属性。当新建连接为 MQTT 5.0 的客户端时,我们可以看到发布消息区域的右下角出现了一个 Meta 按钮。点击该按钮即可看到配置发布时属性的卡片,在卡片顶部可以配置用户属性。

mqttx-user-properties-publish

从 v1.13.1 开始,订阅时也可以设置用户属性。在 MQTT 5.0 连接的新建或编辑订阅弹窗中,在用户属性下添加键值对,这些属性会随 SUBSCRIBE 报文一起发送。部分 Broker 功能依赖于此,例如消费 EMQX MQTT Streams 时,通过 stream-offset 用户属性指定回放位置。设置了用户属性的订阅会在订阅列表中显示一个图标,点击即可查看这些属性。

SCRAM 增强认证

MQTT 5.0 支持 SCRAM(Salted Challenge Response Authentication Mechanism)增强认证。当您的 MQTT 服务器(如 EMQX)开启了 SCRAM 认证时,您可以在连接配置中的 认证方法 下拉框中选择所需的认证方法。MQTTX 支持:

  • SCRAM-SHA-1
  • SCRAM-SHA-256
  • SCRAM-SHA-512

只需选择您首选的 SCRAM 方法,然后使用用户名和密码连接到服务器。

mqttx-scram

请求响应

点击 Meta 按钮,在输入框内输入一个响应主题:/ack/1,以及一个对比数据:light。然后,在当前连接客户端订阅一个 /ack/1。

在 MQTT 5.0 连接的高级设置中开启请求响应信息,向 Broker 请求 CONNACK 中的 Response Information。Broker 返回该属性后,连接页顶部会显示响应信息和复制按钮,折叠设置时也会保留;点击较长的值可查看完整内容。该值由 Broker 提供,MQTTX 不会自行生成。MQTT 3.x 连接或连接断开时不显示。

MQTT 5.0 响应信息

mqttx-response-topic

内容类型和载荷格式

点击 Meta 按钮,在输入框内输入 Content-Type,并设置 Payload Format Indicator 的值。设置完成后,就可以发布消息了。

mqttx-content-type

订阅标识符和订阅选项

打开订阅主题的弹出框,下方可以设置 Subscription Identifier 和订阅选项,订阅选项包括 No Local、Retain as Published 和 Retain Handling。用户可以在订阅报文中指定一个数字作为订阅标识符,并在消息分发时返回此标识符。这样,客户端就能建立订阅标识符与消息处理程序的映射,当收到 PUBLISH 报文时,可以直接通过订阅标识符将消息定向至对应的消息处理程序。同时,用户还可以配置这些订阅选项来改变服务器的行为。

mqttx-sub-flag

设置

您可以通过点击左侧菜单栏底部的设置按钮或使用快捷方式来访问设置。macOS 用户可以使用 command +,,而其他用户可以使用 control +,。设置页面包括了分为通用、外观和高级三个部分的多项选项。MQTTX Agent 相关的设置(启用、选择模型服务商、配置 MCP 服务器等)请参考 MQTTX Agent。

mqttx-settings

通用

通用设置允许您进行 MQTTX 的基本操作定制:

  • 语言:选择界面语言。
  • 自动检查更新:自动检查是否有新版本。
  • 自动恢复订阅:连接成功后,自动重新订阅所有本地保存的订阅。
  • 多主题订阅:一次订阅多个主题,主题之间用逗号分隔。
  • 最大重连次数:设置最大重连次数,以在网络不稳定的情况下保持连接的连续性。
  • 最大 Payload 显示大小:达到或超过该大小的 Payload 会在消息列表中折叠显示(最小 16 KB,默认 512 KB,最大 2 MB)。

外观

外观设置允许您定制 MQTTX 界面的外观。您可以选择三种主题:Light,Dark 和 Night。另外,还有一个选项可以将 MQTTX 主题与您的操作系统同步,以实现一致的用户体验。

JSON 数据高亮 会实时高亮显示接收到的 JSON 格式 Payload。如果遇到性能问题,可以关闭此选项。

安装 MQTTX CLI 工具

从 v1.10.1 起,MQTTX 桌面客户端支持一键安装 MQTTX 命令行工具。用户只需点击安装按钮,即可自动完成安装过程,无需额外操作。整个过程通过图形界面进行,无需用户跳转到下载页面手动下载和配置。此功能自动提供最新版本的 MQTTX CLI,使得在下载桌面端的同时也能轻松获取到命令行工具,方便用户在多种使用场景下操作。

使用方法:

  1. 进入设置页面 -> 找到 MQTTX CLI -> 点击右侧安装按钮。
  2. 或点击顶部菜单,选择安装 MQTTX CLI 选项。

点击后,桌面客户端会自动下载并安装适合您系统的安装包。在安装过程中,您可能需要输入密码以授权访问权限。安装完成后,您便可以在任何命令行窗口中直接运行 mqttx 命令。

注意:对于 Windows 用户,点击安装后需要手动下载 MQTTX CLI 的 exe 程序,然后在对应目录下进行使用。

mqttx-settings-install-cli

mqttx-menu-install-cli

高级(数据管理)

在高级设置中,包含了数据备份,恢复和历史记录清理。

备份与恢复

在 设置 > 高级 中点击 数据备份,可将连接设置和收发消息导出为 JSON、YAML、XML、CSV 或 Excel。通过 数据恢复 导入备份;恢复后连接保持断开状态。

JSON 备份保留嵌套与空分组、排序及连接归属,单连接导出还会包含其祖先分组。其他格式保持原有连接或消息结构,不包含分组。

JSON 兼容与导入规则
格式兼容

JSON 沿用顶层数组,连接记录保留原有字段。分组记录格式如下:

{
  "id": "collection-id",
  "name": "Production",
  "isCollection": true,
  "parentId": null,
  "orderId": 0
}

parentId 指向同一备份中的父分组;根分组使用 null。连接沿用 parentId 表示所属分组。恢复不依赖记录顺序。

恢复兼容旧版仅包含连接的备份。旧文件不包含分组实体,因此连接恢复到根层级。没有 ID 的旧连接会获得新 ID。旧版 MQTTX 无法导入包含分组记录的 JSON 文件,请使用支持分组备份的版本恢复此类文件。

重复导入与冲突

导入已存在的分组或连接 ID 会更新对应实体。消息 ID 更新该连接已有的消息,备份提供的订阅列表替换该连接的订阅。备份未包含的消息保留在数据库中。重复导入时保留 ID,可避免创建新实体。

恢复拒绝备份内重复的 ID、分组与连接共用的 ID、属于其他连接的子记录 ID、缺失的分组引用和循环层级。验证或数据库操作出错时,整个导入事务回滚,包括分组关系、连接、遗嘱、订阅和消息。

如果必要,您可以清除历史记录以管理您的数据使用或保护您的隐私。

高级设置中还包括:

  • 日志等级:设置写入日志的详细程度,详见 日志。
  • 主题空格检测:高亮显示主题中的空格,避免因空格导致发布和订阅的主题不匹配。
  • 启用 GPU 加速:使用显卡渲染界面,使操作更流畅并降低 CPU 占用。修改此选项后需要重启 MQTTX。如果出现界面卡顿、花屏等显示问题,请检查显卡驱动是否为最新版本,或关闭此选项。
  • 自动解压 GZIP 消息:自动解压接收到的 GZIP 消息,详见 GZIP 解压。

mqttx-advance

忽略 QoS 0 消息

在设置中,您可以选择开启或关闭对 QoS 0 消息的忽略功能。QoS 0(服务质量等级 0)消息是最基本的消息传递方式,不保证消息的交付,也不进行重试。对于某些应用场景,您可能希望忽略这些消息以减少不必要的网络流量或处理开销。

操作步骤

  1. 打开设置页面。
  2. 找到“忽略 QoS 0 消息“选项。
  3. 切换开关至”开启”或”关闭”状态。

功能说明

  • 开启:MQTTX 将忽略 QoS 0 的消息,消息将只显示到页面上,不会将其存储到本地,从而提高性能和减少不必要的存储开销。
  • 关闭:所有 QoS 0 消息将正常接收和处理。

注意:已保存的 QoS 0 消息不会被自动清除。

mqttx-ignore-qos0-message

GZIP 解压

从 v1.13.2 开始,设置页「高级」中的 自动解压 GZIP 消息 开关用于解压接收到的 GZIP 消息,默认关闭。

  • 以 gzip 魔数 1f 8b 开头的接收消息会先解压,再按所选的 Payload 格式或 Schema 解码;不是 gzip 的消息保持不变。
  • 解压失败的消息会被标记为错误,并保留原始内容。
  • 解压成功的消息会在 QoS 旁显示 GZIP 标记,悬停即可看到 已自动解压 GZIP。
  • 该标记会随消息一起保存,关闭开关或重启 MQTTX 后,历史消息中仍会显示。

GZIP 消息标记

脚本

自定义函数

此功能允许用户根据特定的需求或场景,编写自定义的函数代码,自由地对 Payload 的内容和格式进行调整和转化,实现更为精细化的数据管理和处理。如果同时配合定时发送功能,可以实现模拟数据报告的自动化测试等功能。

自定义函数使用示例可以在 scripts-example/function 文件夹中查看。如果你在使用中有更好、更实用的脚本,可以在此提交你的代码,让更多的人可以使用。

使用 JavaScript

mqttx-function

点击左侧菜单栏中的 脚本 按钮进入脚本编辑页面。在 自定义函数页面中,用户可以在顶部的代码编辑器中编写 JavaScript 代码。全局只有一个 execute API,用户需要编写一个接收 value 参数的自定义函数,此参数即为 Payload,函数可以自定义修改 value,最后通过 execute 传参执行自定义函数。

下方还有一个 输入 和 输出 框,可以输入预期的输入值,点击右侧的 测试 按钮可以在 输出 框中查看执行结果。输入值的格式包括 JSON 和 Plaintext,方便用户提前调试自定义函数。测试完成后,可以点击右上角的 保存 按钮,输入自定义函数名称保存自定义函数。保存后即可到连接页面使用,已保存的自定义函数也可以编辑和删除。

默认 JavaScript 函数示例如下:

/**
* @description: 默认脚本
* @param {any} value - Payload
* @param {string} msgType - 消息类型,值是 'received' 或 'publish'
* @param {number} index - 消息的索引,仅在脚本用于发布消息并启用定时消息时有效
* @return {any} - 脚本处理后的Payload
*/
function handlePayload(value, msgType, index) {
  return value.msg
}
execute(handlePayload)

编解码

此功能允许用户根据实际需求编写自定义的编解码文件,来对发送和接收的 Payload 进行编解码。在具体应用中,用户可以根据数据特性或特定的应用场景,编写特定的编解码规则。这个过程类似于为 Payload 设计一种特定的“语言”,并通过编写编解码文件来定义这种“语言”的翻译规则。这样,无论是发送还是接收 Payload,都可以根据这些规则来进行编码或解码,确保数据的正确理解和有效传输。

编解码使用示例可以在 scripts-example/schema 文件夹中查看。如果你在使用中有更好、更实用的编解码,可以在此提交你的代码,让更多的人可以使用。

使用 Protocol Buffers

mqttx-schema-protobuf

点击左侧菜单栏中的 脚本 按钮进入脚本编辑页面。在 编解码页面中,用户可以在顶部的下拉框中选择 Protobuf,然后在代码编辑器中编写 proto 文件。

下方还有一个 输入 和 输出 框,可以输入预期的输入值。输入定义的消息类型的名字之后,点击右侧的 测试 按钮可以在 输出 框中查看执行结果。输入值的格式包括 JSON 、 Plaintext 、Base64 和 Hex,方便用户提前调试自定义的编解码。输入 JSON 或者经过 Base64 和 Hex 编码后的 JSON 字符串,测试完成后,可以点击右上角的 保存 按钮,输入编解码名称保存编解码。保存后即可到连接页面使用,已保存的编解码也可以编辑和删除。

默认 Protocol Buffers 编解码文件示例如下:

syntax = "proto3";

message Person {
  int32 id = 1;
  string name = 2;
}

使用 Avro Schema

mqttx-schema-avro

点击左侧菜单栏中的 脚本 按钮进入脚本编辑页面。在 编解码页面中,用户可以在顶部的下拉框中选择 Avro,然后在代码编辑器中编写 avsc 文件。

下方同样支持输入预期的输入值,点击右侧的 测试 按钮可以在 输出 框中查看编解码的执行结果,使用方法与 Protobuf 基本相同。

使用 Avro 编解码文件示例如下:

{
  "type": "record",
  "name": "Person",
  "fields": [
    { "name": "id", "type": "int" },
    { "name": "name", "type": "string" }
  ]
}

工作流

如果用户同时使用了脚本的自定义函数功能和编解码功能,MQTTX 将使用一种高效的脚本工作流,涵盖了发布和订阅两个阶段。

在发布阶段,脚本工作流首先调用自定义函数来处理输入数据。经过这些自定义函数处理后,产生的消息将被显示出来。随后,将使用编解码对处理后的消息进行编码。

mqttx-script-flow-pub

在订阅阶段,脚本工作流首先接收传入的编码消息。接收到消息后,编解码立即被调用以进行解码。解码后的消息会送入自定义函数进行处理。处理完成后,处理过的消息将被显示出来。

mqttx-script-flow-sub

这种的脚本工作流设计允许用户灵活地在发布和订阅阶段处理数据,并保证了消息在传输过程中的安全和完整性。

使用指南

  1. 导航到连接页面,点击页面右上角的下拉菜单。在下拉菜单中,选择 运行脚本 选项。
    mqttx-script-run
  2. 这将会弹出一个脚本窗口,从中选择选择脚本要应用的位置,选项包括发布、接收和全部。然后,选择需要使用的自定义函数或者编解码。
    mqttx-script-select
  3. 编解码选择框中,选择需要使用的编解码,当前支持 Protobuf 和 Avro 两种编解码。
    mqttx-schema-select
  4. 如果您看到在发布或者订阅的消息卡片上看到脚本使用提示,那么说明脚本功能已经被成功调用。
    mqttx-script-message
  5. 如果您需要取消使用脚本,可以点击顶部状态栏中红色的 停止脚本 按钮,这将停止使用脚本。
    mqttx-script-stop

日志

从 v1.5.0 版本开始,MQTTX 引入了日志功能,以帮助用户调试连接和报告错误。在生产环境中,日志系统会显示四个级别的信息:

  • DEBUG 提供详细的调试信息,包括 MQTT.js 数据包的细节,便于排查问题
  • INFO 用于提示用户操作信息
  • WARN 生成不安全行为或潜在风险的警告
  • ERROR 在失败时产生错误消息

您可以在设置页面的高级设置中修改日志等级。

默认情况下,日志将写入以下位置的日志文件,具体取决于您的操作系统:

操作系统日志文件路径
Linux~/.config/MQTTX/logs/log
macOS~/Library/Application Support/MQTTX/logs/log
Windows%USERPROFILE%\AppData\Roaming\MQTTX\logs\log

每次关闭 MQTTX 时,当前的日志文件都会根据时间戳重命名,格式为YYYY-MM-DDThh-mm-ss.log(UTC 时间)。

mqttx-log

视图器

从 v1.11.0 版本开始,MQTTX 引入视图器功能,提供 MQTT 数据可视化能力,帮助用户更直观地理解和监控消息流。

主题树(Beta)

主题树以层级结构展示 MQTT 主题和消息,让用户能够清晰地了解主题间的层级关系和消息流转。

注意:主题树功能目前为 Beta 版本,可能存在功能不完整或不稳定的情况。

主题树功能位于左侧菜单栏的"新建连接"下方的视图器菜单中。使用时,需要先创建一个连接并订阅相关主题,当订阅的主题收到消息后,主题树会自动更新。

页面主要包含搜索框、操作按钮区、主题树显示区和右侧详情面板等部分。在操作区域,你可以进行一键展开/折叠节点、查看可视化显示,同步连接历史消息为主题树和清除主题树等操作。

mqttx-topic-tree

主题树中的节点分为三类:

  • 根节点(Host 节点):显示当前接收消息的客户端信息,包括客户端 ID、Host 信息、连接名称和包含的子主题节点。
  • 中间节点:包含子主题节点,点击后可以查看当前节点的完整主题路径和包含的子主题。
  • 叶子节点:显示接收到的最新消息,包含完整主题路径、接收时间、Retain 标识和 QoS 值。

每个节点名称旁都会显示子节点数量和消息数量。点击节点前的折叠按钮可以展开或折叠子节点,点击节点本身则在右侧显示详细信息。

拖动分隔线可调整信息面板的宽度,MQTTX 会记住该宽度。子主题区域显示所选节点的直接子节点、数量和下方的层级数。

大型主题树的显示限制
  • 信息面板可占页面宽度的 20%–60%。
  • 最多显示 100 个子主题,之后显示 ... 还有 N 个;标题显示数量和层级,例如 子主题 (55 · 2 层)。
  • 节点超过 1000 个时,点击 全部展开 会先请求确认。

注意:当删除对应的连接或清空连接内的消息时,主题树中对应的内容也会被清空。

可视化主题树

在更多操作中选择"可视化主题树"后,MQTTX 将以图形化方式展示当前连接的主题结构。相比列表形式,这种展示方式更加直观,便于理解主题的分布情况。

mqttx-topic-tree-visual-menu

mqttx-topic-tree-visual

你可以在弹出框上方选择不同的 Host 节点,并调整默认展开层级(默认为 4 层)。通过展开/折叠按钮,可以随时调整查看的层级深度。当鼠标悬停在节点上时,会显示该节点的主题路径、消息数量和子节点数量等信息。

mqttx-topic-tree-visual-tooltip

注意:如果数据在实时更新,可视化树会根据当前展开层级实时刷新。需要查看更深层的数据变化时,可以增加展开层级数。

同步连接数据

当主题树接收到新消息时会自动同步到连接页面的消息列表中。同时,MQTTX 也支持将连接页面的历史消息数据手动同步到主题树视图中。您可以通过以下两种方式进行同步:

  1. 在连接页面:
    • 点击右上角下拉菜单中的"同步主题树"选项
    • 选择要同步的连接
    • 系统会自动将该连接的消息记录转换为主题树结构

    mqttx-sync-topic-tree
  2. 在主题树页面:
    • 点击右上角下拉菜单中的"同步连接数据"选项
    • 选择要同步的连接
    • 查看同步后的主题树视图

    mqttx-sync-connection-data-topic-tree
    mqttx-topic-tree-sync-view

注意:

  • 建议在连接空闲时进行数据同步,以确保数据准确性
  • 同步后的主题树将显示每个主题的最新消息

清空主题树

在更多操作中选择"清除主题树"选项可以清空当前连接的主题树内容。

mqttx-clear-topic-tree

仪表盘

使用 Dashboard 将 MQTT 消息字段展示为数值、仪表盘和趋势图。按本文先连接并接收数据,再配置组件,最后核对实时更新与本地历史记录。

直接在 视图器 → 仪表盘 中配置,无需使用 MQTTX Agent。为每个组件选择连接、主题过滤器与 Payload 字段,即可将不同数据源的指标安排在同一视图中。

MQTTX Dashboard

连接并接收数据

  1. 将 MQTTX 客户端连接到接收设备消息的 Broker。
  2. 订阅设备主题或 MQTT 主题过滤器,例如 factory/+/telemetry。
  3. 在连接的消息列表中确认消息已到达。

Dashboard 使用 MQTTX 接收到的消息。在组件中选择主题过滤器,不会替客户端创建该主题的订阅。

在已收到的 Payload 中确定需要展示的数值字段。例如:

{
  "deviceId": "line-01",
  "temperature": 24.8,
  "humidity": 56,
  "pressure": 1.02
}

将组件的字段设置为 temperature、humidity 或 pressure,以读取对应数值。

为每个指标选择合适的展示方式

  • Big Number:突出当前读数,适合温度、压力或设备发送的计数值。
  • Gauge:将读数放在一个范围内,适合展示 0–100% 的湿度等指标。
  • Line:展示数值随时间的变化,便于检查趋势或测试过程中的波动。

对于准备步骤中的 JSON 示例,分别添加温度 Big Number、湿度 Gauge 和压力 Big Number,再添加一张温度 Line 曲线,检查随时间的变化。

创建 Dashboard

  1. 从左侧栏进入 视图器 → 仪表盘。
  2. 点击新建仪表盘,填写名称和描述。
  3. 点击添加组件,选择 Big Number、Line 或 Gauge。
  4. 配置数据源,以及该组件类型提供的选项。
  5. 拖动和缩放组件,安排展示位置,再按需添加其他指标。

拖动仪表盘列表的右边缘可以调整列表宽度。右键点击某个仪表盘,或使用它的 ⋯ 菜单,可以编辑或删除。

将组件绑定到消息字段

在数据源中配置:

字段选择内容
连接正在接收消息的 MQTTX 连接
主题模式要匹配的主题或 MQTT 主题过滤器
字段Payload 中所需数值的 JSON 路径
回退值无法读取指定字段时使用的数值

实时匹配与历史查询都支持 MQTT +、# 主题过滤器。精确主题用于选择单台设备的读数,主题过滤器用于匹配多个主题。一个共享过滤器不会自动为每台设备创建独立的曲线。

让读数更容易理解

按指标为组件命名。根据所选类型配置颜色、小数位数、单位、范围、阈值或线条样式等可用选项。线条展示支持时,编辑器会提供平滑线条和区域填充选项。

以上例为例,为温度和压力数值组件设置 °C、bar 单位,将湿度仪表盘范围设为 0–100%。折线图可以命名为 Temperature trend (°C),直接说明展示的指标和单位。

不同组件提供的配置项有所区别。图表颜色会跟随 Light、Dark 和 Night 主题。

跟随新消息更新,并查看历史变化

  1. 通过设备或另一个 MQTT 客户端,向组件过滤器匹配的主题发布消息,在选定连接的消息列表中确认消息已到达。
  2. 将组件读数与指定 Payload 字段对照。如果显示回退值,检查 JSON 路径和字段数值。
  3. 再发布一条数值不同的消息,确认数值或 Gauge 读数更新,或 Line 曲线新增数据点。未更新时,检查连接是否有效、Broker 订阅、主题过滤器与组件选择的连接。
  4. 在工具栏选择覆盖已收到消息的时间范围,将展示的历史与本地保存的消息记录对照。

历史查询使用本地消息记录,不会向 Broker 补取 MQTTX 此前没有收到的消息。观察持续的实时更新时,保持消息源继续发布。

布局与历史数据限制
  • 仪表盘列表宽度可设置为 160 至 400 像素,MQTTX 会记住该宽度。
  • 组件使用 12 列网格。
  • 每个组件最多展示所选时间范围内最新的 1,000 个数据点。

示例:让 MQTTX Agent 准备一个数据视图

  1. 按 MQTTX Agent 指南 完成配置并打开 Agent,输入 /,选择 Zero EMQX Skill。
  2. 提交以下请求,创建临时 Broker、发布样本消息并准备 Dashboard:

创建一个 Zero EMQX 临时 Broker,将连接保存为 Factory Demo 并连接,订阅 factory/+/telemetry。向 factory/line-01/telemetry 逐条发送 12 条包含 deviceId、temperature、humidity、pressure 且数值有变化的 JSON 消息,再创建名为 Factory Overview 的 Dashboard:显示温度、湿度和压力读数,并放一张温度趋势图,最后打开面板。

  1. 在操作前询问模式中检查并批准操作,确认 Factory Demo 已连接、订阅存在,并在 factory/line-01/telemetry 收到逐条发送的 JSON 消息。
  2. 打开 Factory Overview,将当前读数与最新消息对照,再选择覆盖样本消息的历史时间范围检查趋势。

后续按上文的手动控件继续编辑 Dashboard。更换 Broker 或数据源时,先连接并订阅,再修改组件的数据源设置。

流量监控

从 v1.11.1 版本后当前流量统计功能已经从连接页面迁移到了视图器菜单下,并增强了数据分析能力。通过可视化图表展示 MQTT Broker 的流量数据,能帮助用户实时监控连接的收发数据状况,直观分析流量趋势和峰值,及时发现潜在的网络问题,优化系统性能和资源配置。

访问流量监控有两种便捷方式:

  • 在连接页面,点击右上角的流量监控图标直接进入
  • 通过左侧菜单栏,选择 视图器 -> 流量监控

从连接页面进入时,MQTTX 会自动帮你订阅 $SYS/# 系统主题,无需手动操作。如果你是从菜单直接访问,则需要先手动订阅系统主题才能看到监控数据。

注意:EMQX 默认只允许本地主机(localhost)上的客户端订阅 $SYS 主题。如果你在远程访问时遇到订阅失败,需要修改 EMQX 的 ACL 规则设置。具体配置可参考 EMQX 文档中的内置 ACL 规则说明。

顶部控制栏

界面上方有连接选择器,当从连接页面跳转时,会自动选中对应的连接,同时可以切换要监控的连接并查看其连接状态。右侧是时间范围的选择器,默认显示近 24 小时的数据。

时间选择器默认提供了过去 5 分钟,30 分钟,1 小时,1 天,1 周等时间范围,点击后可以切换时间范围来查看不同时间段的监控数据。

累计值统计

流量统计中卡片为显示最新的累计值,下面是一个折线图,标识累计值的增长趋势。

mqttx-traffic-monitor-accumulated

速率统计

下面是速率统计,卡片显示最新的速率信息,下面显示的当前时间平均的收发速率。

mqttx-traffic-monitor-rate

注意:速率数据是根据 MQTT Broker 发送系统主题的时间间隔计算得出。采样间隔越短,数据越准确。您可以在 MQTT Broker 配置中调整系统主题的发送间隔以获得更精确的数据。

消息体查看器

从 v1.13.0 开始,视图器新增消息体查看器,用于详细查看单个主题的消息。

在左侧菜单栏选择 视图器 -> 消息体查看器,然后选择连接和主题。可以按全部、已接收或已发送筛选消息。

  • 差异视图:将一条消息与同一主题的上一条消息进行对比,高亮显示变化的内容。可以通过前后切换按钮浏览消息历史,也可以跳回最新消息。该主题需要至少有两条消息。
  • JSON 树:以可折叠的树形结构显示 JSON 格式的 Payload,并支持搜索。选择 可视化 JSON 树 可以以图形方式查看数据结构,设置展开层级,点击节点展开或折叠,右键点击节点可以将其子树复制为 JSON。

其他

连接操作

通过点击顶部的操作栏按钮,您可以快速执行各种连接操作,如断开连接、删除当前连接、导入和导出数据,以及管理定时消息和流量统计等功能。

在连接列表中右键点击连接,可以复制连接、在新窗口中打开,或者复制其 Host 或完整的 Broker 地址。

mqttx-connection

消息处理

您可以通过选择消息栏右上角的 "全部"、"接收" 或 "发布" 按钮来筛选消息。

点击顶部的操作栏按钮,选择 "搜索" 选项,或使用快捷键。macOS 用户可以使用 command + f 快捷键,其他用户可以使用 control + f 快捷键打开主题搜索功能,支持模糊查询主题和负载。

点击连接页顶部工具栏中的 清除历史记录 按钮,可以清除当前连接的发送和接收消息。点击后会先弹出确认框,其中会写明连接名称,确认后才会清除。

mqttx-search

检查更新

点击左下角的 "i" 按钮进入 "关于" 页面,可以查看 MQTTX 的版本信息和相关的 EMQX 信息。点击 "检查更新" 按钮可以检查是否有新版本可用。

mqttx-update

多窗口

在连接列表中,右键单击并选择 "新建窗口" 可以为连接创建一个新窗口。在新窗口中,您可以建立连接、订阅主题、发布和接收消息等。如果有多个连接或需要同时查看接收到的消息,可以创建多个视图窗口并并排显示。从 v1.4.1 版本开始,用户还可以点击顶部的窗口按钮快速创建新窗口。

mqttx-window

mqttx-multi-window

定时消息

在右上角的下拉菜单中,您可以选择 "定时消息" 选项来设置发送频率(以秒为单位)。设置完成后,手动发送一条消息,MQTTX 将按照指定的频率自动发送该消息。

mqttx-timed-message