Master RabbitMQ: Acknowledgements, Dead‑Letter Exchanges, QoS & Channel Tuning

Preface

RabbitMQ abandons heavy transactional messages in favor of a confirmation mechanism to achieve distributed transactions, which greatly decouples components. However, configuring it involves many parameters and adjustments, and Chinese documentation is scarce, so this guide compiles essential settings.

1. Publisher Confirms

Publisher confirms ensure that a message has reached the broker. Once a message arrives, the broker triggers a confirm, which can be of two types:

If the message cannot be routed to any queue, the broker sends a negative acknowledgement (ack = false). An exception occurs when the exchange itself cannot be found; if mandatory is set, a basic.return is triggered before the returnCallback .

If the message can be routed, the broker sends a positive acknowledgement (ack = true) when all queues have accepted it. For persistent messages, the ack is sent after the message is safely written to disk; for mirrored messages, the ack is sent after all mirrors have stored the message.

2. Consumer Acknowledgements (Delivery Acknowledgements)

Consumer acknowledgements guarantee that a consumer has successfully processed a message. After a consumer registers, the broker pushes the message via basic.deliver, attaching a unique delivery tag. In manual‑ack mode, the consumer must explicitly acknowledge the message; otherwise the broker will redeliver it because it has been persisted to disk. Acknowledgement is required for both success and failure to avoid severe issues.

3. Dead Letter Exchanges

Messages can be routed to a dead‑letter exchange in three situations:

When the message is rejected or nacked with requeue=false.

When the message exceeds its time‑to‑live (TTL).

When the queue length exceeds its maximum.

Setting a single args entry is sufficient.

channel.exchangeDeclare("some.exchange.name", "direct");
Map<String, Object> args = new HashMap<>();
args.put("x-dead-letter-exchange", "some.exchange.name");
channel.queueDeclare("myqueue", false, false, false, args);

4. QoS

Channel prefetch (QoS) limits the number of unacknowledged messages a channel can have. If the limit is exceeded, the broker stops delivering new messages to that channel. Increasing the value raises throughput but also consumes more broker memory; a range of 100‑300 is often a good starting point.

Setting the value too high may cause all messages to pile up on slow consumers, making the queue appear empty while the client is overloaded. Setting it too low underutilizes resources. The optimal setting depends on network throughput and consumer processing speed (e.g., fast in‑memory processing vs. slow database operations).

QoS is calculated per channel, which may be shared by multiple consumers, making it cumbersome. An alternative is to set a per‑consumer prefetch buffer.

Example:

// 1. Apply a global limit of 10 unacknowledged messages per consumer
Channel channel = ...;
Consumer consumer = ...;
channel.basicQos(10); // Per consumer limit
channel.basicConsume("my-queue", false, consumer);

// 2. Apply separate limits for two queues
Channel channel = ...;
Consumer consumer1 = ...;
Consumer consumer2 = ...;
channel.basicQos(10); // Per consumer limit
channel.basicConsume("my-queue1", false, consumer1);
channel.basicConsume("my-queue2", false, consumer2);

// 3. Set per‑channel and per‑consumer limits (not recommended)
Channel channel = ...;
Consumer consumer1 = ...;
Consumer consumer2 = ...;
channel.basicQos(10, false); // Per consumer limit
channel.basicQos(15, true); // Per channel limit
channel.basicConsume("my-queue1", false, consumer1);
channel.basicConsume("my-queue2", false, consumer2);

5. channelCacheSize

This parameter defines the maximum number of idle channels that can be kept open. In high‑concurrency scenarios, a too‑small value causes frequent channel creation and closure. Since version 1.6, Spring AMQP raised the default from 1 to 25. You can monitor channel churn in the RabbitMQ admin UI and increase the cache size if needed.

When encountering connection errors, consider increasing the channel cache size.

6. Other Parameters and Configurations

delivery tags

Delivery tags are sequential identifiers for messages on a channel, used to uniquely identify each message within the queue.

Blocked Connection Notifications

If the broker runs low on resources (e.g., memory, CPU), it sends a blocked notification to all producers. Applications can listen for this event and handle it appropriately.

ConnectionFactory factory = new ConnectionFactory();
Connection connection = factory.newConnection();
connection.addBlockedListener(new BlockedListener() {
    public void handleBlocked(String reason) throws IOException {
        // Connection is now blocked
    }
    public void handleUnblocked() throws IOException {
        // Connection is now unblocked
    }
});

In practice, the management console also warns about blocked connections, but handling it programmatically can prevent unexpected exceptions.

Multiple

The multiple flag controls bulk acknowledgements. If true, acknowledging a higher delivery tag also acknowledges all lower tags. If false, only the specific tag is acknowledged. Using multiple=true on a channel with many consumers is generally discouraged.

basic.nack

When the broker encounters an internal error, it may send a basic.nack without automatically requeueing the message. The producer must handle this case and possibly resend the message. A basic.nack is only delivered if an internal Erlang process error occurs.

Questions for further investigation:

Where should MQ listeners be configured—per microservice or centrally in the broker? If each service configures its own concurrency, does the number of listeners grow unboundedly with node count?

How to configure SSL and max‑queue‑length settings?

RabbitMQ knowledge base: http://rabbitmq.org.cn/