How to introspect dead-letter queues with RabbitMQ

Why you cannot "look" into a RabbitMQ queue?

It’s tempting to think of queues like databases: stores of messages you can browse, query, or peek into at will. But RabbitMQ doesn’t work that way. By design, RabbitMQ treats queues as strictly FIFO (First-In, First-Out) pipelines: once a message is in the queue, the only supported way to access it is by consuming it from the front. There's no API to peek at arbitrary messages, search for a specific one, or pick one at random.

This behavior often surprises developers coming from systems where messages or tasks can be introspected or filtered before processing. In this article, we’ll explore how to deal with this constraint and how to properly introspect a queue's content before republish part of it.

Reading random messages from a RabbitMQ queue

We have to use RabbitGUI to introspect our dead-letter queue. It is a RabbitMQ IDE that lets you look at a queue's messages, filter them, and eventually re-publish them where needed. To get started, open RabbitGUI and connect to your RabbitMQ server. Once connected, you can navigate to your queue and go to the "Consume" tab and hit "Extract messages".

What RabbitGUI does under the hood is to consume messages from the queue and store them securely in a local database. This allows you to browse, filter, and search through messages at will without all the limitations from RabbitMQ.

At this point, note that all messages have been removed from the queue and only exist in your RabbitGUI's local database. This is a crucial point: RabbitMQ does not allow you to peek at messages without consuming them. This means that you should try to republish messages eventually and not keep them forever in RabbitGUI.

You can filter any property of the message, such as the routing key, queue, or death count. This is useful if you want to find specific messages or if you just want to have statistics about the number of messages with each routing key for instance.

How to read messages headers in RabbitMQ?

Simply open the "Headers" tab of the message to list all of the message headers. RabbitGUI will display all the headers in a user-friendly way, allowing you to see the content of each header and its value.

As always with RabbitGUI, you can click on the name of a queue or exchange to navigate to it and see its details.

How to re-publish messages from dead-letter queues?

RabbitGUI lets you re-publish all or only a subset of messages back to RabbitMQ. You can do this by selecting the messages you want to re-publish, going to "Actions", and selecting "Re-publish messages". You can also choose to re-publish all messages at once by clicking "Select all.

You are presented with a modal where you can choose the destination queue and exchange. You can also choose to re-publish messages with a different routing key or a different exchange, which is useful if you want to re-route messages to a different queue.

To double-check what you are about to re-publish, RabbitGUI shows you a preview of the values it will use when you hit re-publish. This is a great way to ensure that you are not re-publishing messages that you don't want to.

How to throttle messages while re-publishing them with RabbitMQ

When re-publishing messages using RabbitGUI, you might want to avoid overwhelming your RabbitMQ server with too many messages at once. This is especially important if you are dealing with a large number of messages in your dead-letter queue.

A great option is to throttle the re-publishing of messages. This is useful if you want to avoid overwhelming your RabbitMQ server with too many messages at once. You can do this by enabling "Throttling" in the modal and choosing the desired rate.

Conclusion

Even tho RabbitMQ does not allow you to peek into queues, you can still introspect dead-letter queues using RabbitGUI. It is a tool worth considering if you often deal with dead-letter queues and need to re-publish messages.