ApsaraMQ for RocketMQ uses load balancing policies to control how producers route messages to queues and how brokers assign messages or queues to consumers. The consumer-side policy depends on your TCP client SDK version.
How it works
ApsaraMQ for RocketMQ supports two consumer load balancing models:
| Model | Consumer behavior | Compatible with | Key characteristic |
|---|---|---|---|
| Message-based | Brokers distribute individual messages to consumers. Multiple consumers can process messages from the same queue. | TCP client SDK for Java V2.x.x.Final, TCP client SDK for C++ V3.x.x | No idle consumers when consumer count exceeds queue count |
| Queue-based | Brokers assign entire queues to consumers. Each queue is processed by exactly one consumer. | TCP client SDK for Java V1.x.x.Final, TCP client SDK for C++ V1.x.x and V2.x.x | Consumer count should not exceed queue count to avoid idle consumers |
Producer load balancing works the same way in both models:
Unordered messages (normal, transactional, scheduled, and delayed messages): Producers send messages to queues in round-robin order.
Ordered messages: Producers send all messages with the same sharding key to the same queue.
Load balancing policies compatible with the SDK for Java V2.x.x.Final and the SDK for C++ V3.x.x
These load balancing policies distribute individual messages -- not entire queues -- to consumers. Multiple consumers can process messages from the same queue simultaneously, and no consumer sits idle even when the consumer count exceeds the queue count.
Prerequisites
To use these load balancing policies, upgrade your TCP client SDK:
TCP client SDK for Java: Upgrade to V2.x.x.Final. The instance must be deployed in one of these regions: China (Hangzhou), China (Qingdao), China (Beijing), China (Zhangjiakou), China (Hohhot), China (Shenzhen), China (Chengdu), Germany (Frankfurt), or Indonesia (Jakarta).
TCP client SDK for C++: Upgrade to V3.x.x. The instance can be deployed in any region.
Producer routing
Producer load balancing is the same regardless of the SDK version:
Unordered messages (normal, transactional, scheduled, and delayed messages): Producers send messages to queues in round-robin order. In this example, three queues are available. The producer sends Msg1 to Queue 1, Msg2 to Queue 2, Msg3 to Queue 3, Msg4 back to Queue 1, and so on.
Ordered messages: Producers send all messages with the same sharding key to the same queue. In this example, all messages with sharding key 1 go to Queue 1, and all messages with sharding key 2 go to Queue 2.
Consumer assignment for unordered messages
For unordered messages, brokers evenly distribute all messages in a topic across consumers in the same group. Messages in the same queue can be consumed by different consumers simultaneously.
In this example, four messages in Queue 2 are distributed to Consumer 1, Consumer 2, Consumer 3, and Consumer 4 respectively. Each consumer processes messages independently, regardless of which queue the messages belong to.
Consumer assignment for ordered messages
For ordered messages, brokers distribute messages based on sharding keys. All messages with the same sharding key go to the same consumer, which preserves the production order. Messages with different sharding keys can be distributed to different consumers.
: Messages with this background color belong to Queue 1. For example, Msg2-1 is the second message in Queue 1, and its sharding key is 1.
: Messages with this background color belong to Queue 2. For example, Msg3-2 is the third message in Queue 2, and its sharding key is 2.
In this example:
Msg1-1, Msg2-1, and Msg3-1 all go to Consumer 1 because they share sharding key 1.
Messages with sharding key 2 all go to Consumer 2.
Msg4-3 and Msg4-4 go to different consumers because they have different sharding keys.
Load balancing policies compatible with the SDK for Java V1.x.x.Final and the SDK for C++ V1.x.x and V2.x.x
These load balancing policies assign entire queues to consumers. Each queue is processed by exactly one consumer at a time. The assignment policy for unordered messages and ordered messages is the same.
How queues are distributed
The ApsaraMQ for RocketMQ architecture includes brokers and name servers. A broker reports topic route information to a name server. By default, messages in a topic are distributed among 8 queues per broker. A queue is a logical concept. The broker then assigns these queues evenly to all consumers in the same group.
Producer routing
Producer load balancing is the same as in the SDK for Java V2.x.x.Final and the SDK for C++ V3.x.x:
Unordered messages: Producers send messages to queues in round-robin order.
Ordered messages: Producers send all messages with the same sharding key to the same queue.
For details and diagrams, see Producer routing above.
Consumer assignment
Because each queue can only be assigned to one consumer at a time, the consumer-to-queue ratio directly affects resource utilization:
More consumers than queues: Extra consumers remain idle. For example, with 8 queues and 10 consumers, 2 consumers do not process any messages.
Equal consumers and queues: Each consumer processes messages from exactly one queue.
Fewer consumers than queues: Each consumer processes messages from multiple queues.
Message accumulation
With queue-based load balancing, a consumer may fail to process messages in its assigned queue promptly due to hardware constraints, system limits, Remote Procedure Call (RPC) issues, or Java Garbage Collection (GC) pauses. When this happens, messages accumulate in the queue.