动作执行失败告警处理指南
动作执行失败告警表示在过去 30 分钟内，部署中数据集成动作执行失败的次数已超过设定阈值。
该情况通常意味着 EMQX 在执行数据集成规则时，消息已经通过规则引擎处理，但在向外部系统写入数据时出现异常，导致动作未能成功执行。常见问题包括数据不符合目标存储要求、数据唯一性冲突，或外部服务连接异常等。
数据缺失或字段类型不匹配
问题描述
在执行数据集成动作时，如果写入目标系统的消息中缺少必需字段，或字段类型与目标存储的 Schema 不一致，则可能导致动作执行失败并触发该告警。
在部署日志中，如果出现 error missing_field 或 invalid_text_representation 等报错信息，则通常表明存在字段缺失或字段类型不匹配的问题。
常见原因
- 消息 payload 中缺少目标系统要求的必需字段。
- 字段类型与目标存储定义不一致（如字符串写入数值字段）。
- 时间戳字段精度（秒 / 毫秒 / 纳秒）与目标存储要求不一致。
处理方法
- 确保消息 payload 中包含所有必需字段，并且字段类型符合目标存储要求。
- 对可选字段使用默认值，或在规则 SQL / 规则逻辑中进行类型转换或容错处理。
- 对时间戳字段注意精度设置，确保与目标存储系统保持一致。
数据唯一性冲突
问题描述
在向数据库类目标系统写入数据时，如果写入的数据在主键或唯一约束字段上与已有记录发生冲突，则会导致动作执行失败。
在部署日志中，如果出现 unique_violation 或 duplicate key value violates unique constraint 等报错信息，则通常表明存在数据唯一性冲突。
常见原因
- 同一条数据被重复写入。
- 上游规则逻辑或消息重试机制导致动作被重复执行。
- 时间戳精度过粗，导致不同数据在唯一约束下发生冲突。
处理方法
- 避免重复写入同一条数据，检查上游规则逻辑或消息重试机制。
- 选择更具唯一性且不易重复的字段组合作为主键或唯一约束。
- 根据业务需求，评估是否需要移除或放宽唯一约束，以允许重复数据存在。
外部服务不可用或连接异常
问题描述
当目标系统不可达或连接异常时，数据集成动作在执行过程中无法成功将数据写入外部服务，从而导致动作执行失败。
在部署日志中，如果出现 unrecoverable_error、timeout 或 producer_is_still_disconnected_after_retry 等报错信息，则可能符合此类情况。
常见原因
- 目标服务不可用或服务异常。
- 网络延迟、网络中断或连接超时。
- 目标系统负载过高，导致连接被拒绝或请求超时。
- 缺少写入目标服务所需的权限或凭证配置错误（如 GCP Pub/Sub）。
处理方法
- 确认目标系统地址和端口配置正确，并保证服务正常运行。
- 检查网络连通性，确保 EMQX 与目标系统之间通信畅通。
- 监控目标系统负载，避免因高并发或资源不足导致连接失败。
- 确保使用的账号或凭证具有执行相关操作所需的权限。
排查步骤
登录 EMQX Cloud 控制台。
打开部署日志，将“错误类型”过滤为数据集成。日志中的报错信息会因目标数据库或外部服务类型的不同而有所差异，建议结合实际使用的目标系统类型，参考具体报错内容进行排查。
通常报错信息中会包含出错的数据库表名或目标资源以及对应的错误原因。可根据这些信息反推定位到对应的规则和输出动作。对于不确定或难以判断的日志信息，可提交工单联系技术支持获取更多详情。
如需修改规则或动作配置，进入数据集成 -> 规则列表 或输出动作列表，点击对应规则或动作的编辑按钮进行修改。
监控与统计
在 EMQX Cloud 控制台的数据集成页面中，可以查看单个输出动作的成功与失败数量统计，用于持续观察动作执行情况。
