PAYATHON 2026

IBM MQ 消息达到 BOTHRESH 后未进入 backout queue 如何排查

数据小陈

结论:setSessionTransacted(true) 只能保证 listener 抛出异常时 JMS Session 会回滚,并不代表消息达到阈值后就一定进入 backout queue。消息是否进入 backout queue,要看 IBM MQ 在回滚后根据 BackoutCount、输入队列的 BOTHRESH、BOQNAME、目标队列是否为本地队列,以及实际运行用户的 PUT 权限共同判断。输入队列 CURDEPTH>0 但 browse 为空时,先怀疑消息仍在未提交事务中、被锁住,或者已经被移到 DLQ/BOQ 但没在预期位置查看,不要直接归因于 MQ PUT 失败。

先确认触发链

  1. listener 方法必须把异常抛给容器,不能被 try/catch 吞掉,也不能让自定义 ErrorHandler 把异常处理成正常返回。
  2. 容器必须真正回滚 JMS Session。只设置 setSessionTransacted(true) 还不够,还要确认没有配置外部 JmsTransactionManager/JTA 覆盖该行为;如果用了事务管理器,以事务管理器的回滚结果为准。
  3. MQ 在回滚时递增消息的 BackoutCount,达到 BOTHRESH 后再按 BOQNAME 转投。BOTHRESH=0 通常表示不启用该机制,先确认它不是 0。
  4. BOQNAME 应指向同一队列管理器上的本地队列;如果回退队列不存在或不可用,检查 SYSTEM.DEAD.LETTER.QUEUE 和 MQ 错误日志,消息可能去了 DLQ。

排查步骤

先看容器配置和 listener 是否真的回滚:

@Bean
public DefaultJmsListenerContainerFactory jmsListenerContainerFactory(
        ConnectionFactory connectionFactory) {
    DefaultJmsListenerContainerFactory factory = new DefaultJmsListenerContainerFactory();
    factory.setConnectionFactory(connectionFactory);
    factory.setSessionTransacted(true);
    // 若使用 JmsTransactionManager/JTA,确认事务管理器配置和回滚规则
    return factory;
}

listener 中不要吞异常:

@JmsListener(destination = "INPUT.QUEUE")
public void onMessage(Message message) throws JMSException {
    try {
        repository.save(/* ... */);
        jmsTemplate.convertAndSend("NEXT.QUEUE", payload);
    } catch (DataAccessException e) {
        log.error("处理失败,抛出以触发回滚", e);
        throw e;
    }
}

如果 listener 内用 JmsTemplate 发送下一个队列,要注意它默认不一定加入 listener 的 JMS 事务;这会影响下游的重复或丢失语义,需要单独配置并做幂等。

用 MQSC 核对队列属性和状态:

DIS QLOCAL('INPUT.QUEUE') BOQNAME BOTHRESH CURDEPTH
DIS QLOCAL('BACKOUT.QUEUE') CURDEPTH
DIS QLOCAL('SYSTEM.DEAD.LETTER.QUEUE') CURDEPTH
DIS QSTATUS('INPUT.QUEUE') CURDEPTH IPPROCS OPPROCS UNCOM

如果 UNCOM>0,说明有未提交消息;MQ Explorer 浏览不到是可能的。此时要查是谁持有长事务、连接是否卡住,必要时等待事务结束或处理异常连接。

再核对实际运行用户的权限:

dspmqaut -m QM1 -t q -n BACKOUT.QUEUE -p appuser

重点看 put;AUTHADD(PUT) 记录存在,不代表实际连接用户一定匹配。还要确认 BOQNAME 没有写成远程队列或错误队列名。

最后查 MQ 错误日志和 DLQ。若 backout queue 的 PUT 失败、队列不存在或权限不足,MQ 侧通常会有 AMQ 错误记录;消息也可能进入 DLQ。不要只看 MQ Explorer 的输入队列页面。

注意事项

  • setSessionTransacted(true) 只控制 JMS Session 事务;IBM MQ backout queue 是否生效不由它决定。
  • BOTHRESH、BOQNAME 配在输入队列上;回退队列必须是可用本地队列。
  • 浏览为空但深度大于 0 时,先查 UNCOM 和活动连接,再判断是否真的没有入 BOQ。
  • 生产环境修改事务和回退策略前,先做幂等和重复消费验证。

备注:内容仅供参考。