Quality of service and connection management

In MQTT, quality of service (QoS) controls the assurance of message delivery over the underlying transport. IBM® Integration Bus handles messages in different ways, depending on whether the QoS level is 0, 1, or 2.

The three levels of QoS are defined in the MQTT Protocol Specification. The following list provides a summary of the three levels:

QoS 0: At most once delivery (fire and forget)
QoS 1: At least once delivery (acknowledged delivery)
QoS 2: Exactly once delivery (assured delivery)

The open source Eclipse Paho MQTT client, which implements the MQTT protocol specification, is embedded in IBM Integration Bus. The MQTT nodes use the Paho client to handle the exchange of MQTT protocol messages that are associated with the different QoS levels.

When IBM Integration Bus connects to an MQTT server to publish a message with QoS 1 or QoS 2, the clean session flag is set to 0 (false). Therefore, any publications that are in flight when a connection is lost are delivered when IBM Integration Bus reconnects to the server. For subscriptions, the clean session flag is set to 1 (true). When an MQTTSubscribe node connects, or reconnects, to an MQTT server, the connection is treated as a new connection.

Behavior of the MQTTSubscribe node

The QoS level for received messages applies only to the transfer of the messages from the MQTT server to IBM Integration Bus. When a message with QoS 0 is successfully received by the Paho client, the MQTTSubscribe node propagates the message to the Out terminal. When a message with QoS 1 or QoS 2 is successfully received, the Paho client must acknowledge the receipt of the message before it can be processed by the node. After the transfer is successfully acknowledged and completed, the QoS level has no further effect on how the message is handled by IBM Integration Bus.

If the network connection to the MQTT server is lost, the MQTTSubscribe node retries the connection after 5 seconds. The interval between reconnection attempts increases by 5 seconds on each attempt, up to a maximum of 2 minutes. There is no limit to the number of reconnection attempts. These attempts are logged in the MQTT Activity Log.

If messages arrive faster than they can be processed by IBM Integration Bus, message receipt is blocked until the message flow is able to process them.

When an MQTTSubscribe node receives a message, the local environment is populated with the QoS of the message by using the QualityOfService variable. For more information about the local environment variables, see MQTTSubscribe node.

Behavior of the MQTTPublish node

The QoS level for published messages applies to the transfer of the message from IBM Integration Bus to the MQTT server. When the MQTTPublish node publishes a message with QoS 0, an acknowledgment of the transfer is not expected. When the MQTTPublish node publishes a message with QoS 1 or QoS 2, the node waits for up to 30 seconds for the Paho client to confirm that the MQTT server has acknowledged receipt of the message. If no acknowledgment is received after this time, the node retries the publish. If this second attempt fails, an exception is produced with message BIP12099, and the node propagates the message to the Failure terminal if the node has a Failure terminal connected. If a Failure terminal is not connected, the message is rolled back to the input node.

Diagnosing transport issues

A connection failure at the network level generates an exception with message BIP12096. The MQTT resource statistics measurement FailedConnections, which reports the total number of attempted connections to an MQTT server that have failed since the last integration server restart, is also incremented.

The following connection issues are logged in the MQTT Activity Log:

Failed to connect to an MQTT server
Reattempted the connection to an MQTT server
Lost the connection to an MQTT server
Failed to disconnect from an MQTT server

The Activity Log also records both successful and unsuccessful attempts to publish a message to a topic, together with the QoS of the message. When an MQTTSubscribe node successfully subscribes to a topic, or receives a message from a topic, this success is also logged, together with the QoS of the subscription or the message.