SQL 匹配失败告警处理指南

SQL 匹配失败告警表示在过去 30 分钟内，部署中数据集成规则执行失败的次数已超过设定阈值。

该情况通常意味着 EMQX Cloud 在执行数据集成规则时，消息已经进入规则引擎，但在 SQL 匹配或处理过程中发生异常，导致规则未能正确执行。常见问题包括消息 payload 的格式或编码不符合预期，或规则中使用的函数、表达式与实际数据结构不匹配。

消息 payload 格式或编码与预期不符

问题描述

当规则 SQL 接收到的消息 payload 不是合法的 JSON，或 payload 数据被截断、损坏，或编码方式不是 UTF-8 时，SQL 在解析 payload 或访问字段时可能失败，从而触发 SQL 匹配失败告警。

在部署日志 中，如果出现 invalid_json、decode_json_failed 等报错信息，则通常符合此类情况。

常见原因

• JSON 格式不合法，例如使用单引号代替双引号、存在尾随逗号。
• 时间戳字段未按 JSON 规范使用字符串形式。
• 消息 payload 在传输过程中被截断或损坏。
• 消息编码不是 UTF-8。

处理方法

• 确保客户端发送的消息 payload 格式正确、完整，并使用 UTF-8 编码。
• 使用 MQTT 客户端订阅规则所筛选的主题，获取原始 MQTT payload 数据，对比分析格式问题并进行修复。

函数或表达式类型或结构不匹配

问题描述

当规则 SQL 中使用的函数或 jq 表达式与实际 payload 中字段的类型或结构不一致时，函数执行可能失败或抛出异常，从而导致规则执行失败。

在部署日志 中，如果出现 function_clause、jq_exception 或 jq error 等报错信息，则通常符合此类情况。

常见原因

• SQL 中对字段类型的假设与实际 payload 不一致。
• jq 表达式路径与实际 JSON 结构不匹配。
• 对空值或缺失字段直接执行函数或表达式。

处理方法

• 核对 payload 的实际结构和字段类型，并相应调整规则 SQL 逻辑。
• 确保字段类型与所使用的函数或表达式匹配。
• 在 SQL 或 jq 表达式中增加安全检查，例如使用 is_not_null() 等函数，避免对空值直接操作。

排查步骤

1. 登录 EMQX Cloud 控制台。

2. 打开部署日志，将“错误类型”过滤为数据集成。

   • 若日志中出现 invalid_json、decode_json_failed 等报错，则通常属于消息 payload 格式或编码与预期不符场景。示例日志如下：

     clientid: XXXXX, reason: {error,{decode_json_failed,...}}

   • 若日志中出现 function_clause、jq_exception 或 jq error 等报错，则通常属于函数或表达式类型或结构不匹配场景。示例日志如下：

     WHERE clause exception for rule: XXXXX failed: {error,function_clause,...}

3. 从日志信息中获取对应的 rule_id 以及具体的报错原因。

4. 打开数据集成 -> 规则列表，根据 rule_id 定位到对应的规则，点击编辑，对 SQL 逻辑或相关配置进行修改。

   

监控与统计

1. 在 EMQX Cloud 控制台的数据集成 页面中，可以查看单个规则 SQL 的执行成功次数与失败次数统计，用于持续观察规则执行情况。

   

2. 打开告警 -> 告警列表，可查看 SQL 匹配失败告警的触发记录及其触发次数，用于判断问题是否已得到缓解。