AMQP Dead Letter Exchange Workbench
Trace how failed AMQP messages leave a source queue, pass through a DLX, and arrive in a dead letter queue with useful evidence.
AMQP Dead Letter Exchange Workbench
Follow one message from a producer into a source queue, then decide whether it is acknowledged, rejected, expired, overflowed, or sent to a dead letter exchange for inspection. The goal is to see that a DLX is not just a separate queue: it is a normal exchange used for the second publish.
The DLX policy belongs to the source queue, not to the producer. The queue decides where failed messages go.
Rejected with requeue=false, TTL expiry, queue length overflow, and quorum delivery limit are the core cases.
A queue can override the key with x-dead-letter-routing-key; otherwise original routing keys are used.
Inspect x-death, fix the cause, then retry, archive, or discard with intent.
Scenario controls
Use presets first, then adjust the broker conditions to test edge cases.
Message path
The producer publishes a telemetry message with routing key sensor.room1.temp.
The consumer refused the message and did not ask the broker to put it back in the source queue.
The message becomes a dead letter because the consumer rejected it with requeue=false.
The DLX publish uses failed.telemetry, so the failed queue binding can be simple and predictable.
Monitor DLQ depth and alert when failures appear faster than triage can process them.
Use the failure reason and original routing keys before deciding whether retry is safe.
The DLX is an exchange. The DLQ is just a queue bound to that exchange. Routing still depends on bindings and routing keys.
requeue=true is not dead lettering.
A rejected message with requeue=true returns to a queue and may be redelivered; it does not go to the DLX at that moment.
TTL is not always visible as an instant timer pop; messages may wait behind older messages until they reach the head.
Keep the target exchange and queue available, and use quorum at-least-once dead lettering when the safety requirement demands it.
Decision trace
reject/nack
Dead-letter only when: consumer sends basic.reject or basic.nack with requeue=false.
TTL
Expired when: message age is greater than or equal to the lower applicable queue or per-message TTL.
maxlen
Overflow when: queue length exceeds the configured message or byte limit, so messages are dropped or dead-lettered.
delivery_limit
Quorum only: a poison message is dead-lettered after more returns than the configured quorum delivery limit.
routing key
DLX publish uses: x-dead-letter-routing-key if configured, otherwise the original routing keys.
x-death
Evidence records: queue, reason, count, exchange, routing keys, and first/last death fields.
AMQP DLX quick reference
Prefer policies such as dead-letter-exchange and dead-letter-routing-key so operators can change routing without redeclaring application queues.
Applications can declare x-dead-letter-exchange and x-dead-letter-routing-key, but those hard-coded arguments are harder to change later.
Use the exact reason names rejected, expired, maxlen, and delivery_limit when teaching or building dashboards.
If the DLX does not exist when the message must be dead-lettered, the message can be dropped. If no binding matches, normal exchange routing rules apply.
Retries should usually go through a separate retry queue or controlled republish path, not blind automatic loops that hide poison messages.
DLQs are useful for malformed telemetry, commands that expired before delivery, burst overflow archives, and repeated device-specific processing failures.