EMQX 连接终止日志分级优化：当报文超过 `mqtt.max_packet_size` 时以 warning 记录 `emsgsize` 断开原因

后端物联网消息队列通信【免费下载链接】emqxThe most scalable and reliable MQTT broker for AI, IoT, IIoT and connected vehicles项目地址https://gitcode.com/gh_mirrors/em/emqx点击查看免费下载导读本篇文章围绕 EMQX 开源仓库中的变更记录 fix-16956.en.md 展开深入解析一项关于连接终止日志分级的细节优化当客户端因发送超过mqtt.max_packet_size上限的 MQTT 报文而被服务端终止连接断开原因为emsgsize时EMQX 将不再以默认的 info 级别记录该事件而是提升为 warning 级别输出。读者通过本文可以理解emsgsize断开原因的完整产生链路从 TCP 层packet_size到连接进程终止、掌握mqtt.max_packet_size与mqtt.max_connect_packet_size两个配置项的语义与默认值并能够结合源码与测试用例在运维实践中通过日志级别快速甄别报文超限这一异常断开场景。一、变更背景报文超限断开是值得关注的异常事件在 EMQX 的连接生命周期中客户端连接被终止的原因多种多样。其中emsgsize表示接收到的数据包大小超出上限。在 MQTT 场景下这通常意味着客户端发送了超过mqtt.max_packet_size配置上限的报文——例如某个设备异常地一次性写入超大负载或者使用了错误的协议帧封装。EMQX 在 emqx_connection.erl 中将emsgsize归类为正常 socket 错误?IS_NORMAL_SOCKET_ERROR宏其注释说明了来源Packet size too large when{packet, mqtt}option is set forgen_tcp。也就是说当监听器以整帧whole-frame模式解析 MQTT 报文时gen_tcp会在底层就拒绝超过packet_size的报文并以emsgsize错误上抛。虽然它在代码语义上属于正常关闭但对运维而言客户端发送超大报文被断开往往是配置不当、客户端实现缺陷或潜在攻击的信号需要引起重视。正是基于这一考虑变更 fix-16956.en.md 将此类断开的日志级别从 info 提升为 warningLog client connection termination at warning level instead of info when the reason isemsgsize(received packet exceedsmqtt.max_packet_size).二、核心实现terminate_log_level/1决定终止日志级别本次变更的落点在连接进程的终止路径上。在 emqx_connection.erl 的terminate/2中终止事件通过?tptelemetry 事件上报其级别由terminate_log_level(Reason)动态决定?tp(terminate_log_level(Reason), terminate, #{reason Reason}), maybe_raise_exception(Reason).而terminate_log_level/1的实现正是本次变更的关键terminate_log_level({shutdown, emsgsize}) - warning; terminate_log_level(_Reason) - info.也就是说当终止原因为{shutdown, emsgsize}时terminate事件以warning级别记录其余所有原因包括正常关闭closed、{shutdown, normal}等仍保持原有的info级别。这样一来运维日志中客户端报文超限被断开与普通连接关闭的日志级别被清晰区分便于后续基于日志级别做告警与统计而不会淹没在大量 info 级别的正常断开记录中。三、emsgsize断开原因的完整产生链路要理解这次日志分级的意义需要梳理emsgsize从底层 socket 到连接进程终止的完整链路。相关逻辑分布在 emqx_connection.erl 的几个关键函数中1. CONNECT 阶段受max_connect_packet_size约束在客户端完成 CONNECT 之前监听器listener以packet_size等于max_connect_packet_size默认 64KB的配置接收首帧以便在解析 MQTT CONNECT 报文之前就拒绝过大的报文。这在源码注释中有明确说明emqx_connection.erlBefore CONNECT, the whole-frame transports are set up withpacket_sizeequal tomax_connect_packet_size, so they reject an oversized CONNECT before the...同时connect_too_large_error/2会基于emqx_config:get_zone_conf(Zone, [mqtt, max_connect_packet_size])计算出限制值并在首帧超限时上报cause connect_packet_too_large与limit字段。2. 连接建立后提升到max_packet_size客户端完成 CONNECT 后raise_packet_size_limit/1emqx_connection.erl会把 socket 的packet_size提升为mqtt.max_packet_size的配置值raise_packet_size_limit(#state{ parser {frame, _}, transport Transport, socket Socket, conf Conf }) - #conf{zone Zone} Conf, MaxSize emqx_config:get_zone_conf(Zone, [mqtt, max_packet_size]), _ Transport:setopts(Socket, [{packet_size, MaxSize}]), ok;注释解释了原因监听器起初以 CONNECT 限制接收数据连接建立后需要将限制提升到普通报文的max_packet_size避免普通报文被 CONNECT 限制误伤。只有整帧解析器{frame, _}即{packet, mqtt}模式才读取该packet_size选项。3. socket 错误上抛与连接终止当整帧解析模式下收到超过packet_size的报文时gen_tcp返回emsgsize错误经由handle_info({sock_error, emsgsize}, State)处理最终以{stop, {shutdown, emsgsize}, NState}终止连接进程见测试用例 emqx_connection_SUITE.erl。随后terminate/2中的terminate_log_level({shutdown, emsgsize})命中 warning 分支完成本次变更的日志分级目标。4. 首帧非 MQTT 的特殊记录对于 CONNECT 阶段就发生emsgsize的情况maybe_log_first_packet_non_mqtt/2 会额外以 info 级别记录first_packet_probably_not_mqtt日志提示首帧可能不是 MQTT 报文maybe_log_first_packet_non_mqtt(emsgsize, #state{channel Channel}) - case emqx_channel:info(conn_state, Channel) of idle - ?SLOG(info, #{ msg first_packet_probably_not_mqtt, reason emsgsize }); _ - ok end;同时transport_frame_too_large/1emqx_connection.erl将emsgsize与{invalid_packet, _Data}统一识别为传输帧过大。由此可见本次变更只调整了连接终止事件的日志级别而首帧非 MQTT 的辅助提示仍保持 info两者职责不同、互不干扰。四、配置项详解max_packet_size与max_connect_packet_sizeemsgsize断开的触发条件直接由配置控制其 schema 定义位于 emqx_schema.erl 的mqtt_general/0中配置项类型默认值说明max_packet_sizebytesize()1MBMQTT 报文含 CONNECT 之后的普通报文最大字节数超过则断开max_connect_packet_sizebytesize()64KBCONNECT 报文最大字节数用于连接建立前的整帧限制两个配置项共用同一组校验与转换函数validate_max_packet_size/1emqx_schema.erl拒绝小于 1 的整数拒绝超过?MAX_INT_MQTT_PACKET_SIZE的值MQTT 协议允许的最大报文尺寸非整数一律报错convert_max_packet_size/2emqx_schema.erl支持将256MB之类的字符串形式转换为字节数。在emqx.conf或按 zone 配置中可如下设置mqtt { max_packet_size 1MB max_connect_packet_size 64KB }配置读取路径为emqx_config:get_zone_conf(Zone, [mqtt, max_packet_size])因此不同 zone如默认default、external、internal可以分别设置不同的报文上限实现精细化的流量治理。五、测试验证行为有据可查本次变更的行为在单元测试 emqx_connection_SUITE.erl 中得到了覆盖?assertEqual( ok, emqx_connection:maybe_log_first_packet_non_mqtt(emsgsize, st(#{}, #{conn_state idle})) ), ?assertEqual(ok, emqx_connection:maybe_log_first_packet_non_mqtt(emsgsize, st())), ?assertEqual(ok, emqx_connection:maybe_log_first_packet_non_mqtt(timeout, st())), ?assertMatch( {stop, {shutdown, emsgsize}, _NState}, emqx_connection:handle_info( {sock_error, emsgsize}, st(#{sockstate idle}, #{conn_state idle}) ) ).测试确认了三个要点maybe_log_first_packet_non_mqtt/2对emsgsize无论连接是否处于idle状态以及其他原因如timeout都能正常处理并返回okhandle_info({sock_error, emsgsize}, ...)的返回值精确匹配{stop, {shutdown, emsgsize}, _NState}证明连接进程以{shutdown, emsgsize}作为终止原因退出结合terminate_log_level/1的 clause该终止原因最终映射为 warning 级别日志。六、运维视角如何利用本次变更对于运维与排障人员本次变更带来的直接收益是日志可筛性的提升。在升级到包含该修复的版本后通过warning级别日志即可快速定位客户端发送超大报文被断开的事件无需在大量 info 日志中逐个排查reason emsgsize可以基于日志级别配置告警规则当某客户端频繁触发emsgsize断开时通常是设备端协议栈实现问题如未遵守max_packet_size通告或异常流量应检查对端实现或考虑调大mqtt.max_packet_size若确认是合法业务需要发送大报文可先核对 emqx_schema.erl 中的默认值1MB/64KB按需调整 zone 级配置并注意转换器支持256MB这类字符串字面量写法。总结变更 fix-16956 是一个小而精准的运维体验优化通过 terminate_log_level/1 将{shutdown, emsgsize}终止事件的日志级别从 info 提升为 warning让报文超过mqtt.max_packet_size被断开这一异常场景在日志中更加醒目。它不改变任何协议行为与断开逻辑只是调整了可观测性输出但其背后牵涉的整帧解析、packet_size提升、zone 配置读取与测试覆盖完整展现了 EMQX 连接层从 socket 错误到终止日志的精细化处理思路。赞分享后端物联网消息队列通信【免费下载链接】emqxThe most scalable and reliable MQTT broker for AI, IoT, IIoT and connected vehicles项目地址https://gitcode.com/gh_mirrors/em/emqx点击查看免费下载相关推荐EMQX 集群 RPC 日志治理gen_rpc 3.5.1 升级与连接超时日志节流深度解析EMQX 集群 RPC 日志治理gen_rpc 3.5.1 升级与连接超时日志节流深度解析 导读 当集群中某个节点不可达时EMQX 节点间的 RPC远程过后端物联网消息队列通信EMQX ClickHouse 桥接器健康检查超时处理优化以 connecting 替代 disconnected消除无效重连与日志风暴EMQX ClickHouse 桥接器健康检查超时处理优化以 connecting 替代 disconnected消除无效重连与日志风暴 导读 本篇文章围绕后端物联网消息队列通信EMQX 连接日志 MQTT 报文数据默认脱敏与监听器级 IP 白名单诊断配置指南EMQX 连接日志 MQTT 报文数据默认脱敏与监听器级 IP 白名单诊断配置指南 导读 本文讲解 EMQX 的一项连接日志安全增强 连接日志中的原始 MQT后端物联网消息队列通信创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考