Dead Letter Queues¶
Every channel has a dead letter queue (DLQ) that collects failed deliveries.
What Goes to the DLQ¶
- Deliveries explicitly NACKed by subscribers
- Deliveries that time out (auto-nack)
- Deliveries whose subscriber block raised (auto-nack)
- Deliveries still pending when the channel is closed (force-nack)
- Messages published with no subscribers
Accessing the DLQ¶
Via MessageBus:
Via Channel directly:
Inspecting Entries¶
dlq.size # number of entries
dlq.empty? # true if no entries
dlq.each do |delivery|
puts "#{delivery.message} failed on subscriber ##{delivery.subscriber_id}"
puts " timed out? #{delivery.timed_out?}"
end
The DLQ includes Enumerable, so you can use map, select, count, etc.
Draining for Retry¶
drain yields each entry and removes it from the queue:
drain works on a snapshot. The queue is emptied before the first yield, so size is 0 and each sees nothing while the block runs, apart from entries added during the drain. Those entries (such as a retry that fails again) stay queued for the next drain, so a drain-and-retry block does not loop.
If the block raises, the entry it was handling and the entries not yet yielded go back to the front of the queue in their original order, and the error propagates. If the block exits early with break, the entry it was handling counts as done and only the entries not yet yielded go back.
Without a block, drain returns the array of drained entries:
Real-Time Callback¶
Register a callback that fires whenever a new entry arrives:
channel.dead_letter_queue.on_dead_letter do |delivery|
alert("Dead letter on :#{delivery.channel_name}: #{delivery.message}")
end
Clearing¶
Discard all DLQ entries:
Or clear the entire channel (including DLQ, pending deliveries, and timeout tasks):