Comandos Essenciais do RabbitMQ para Gerenciamento de Filas: Declarar, Listar, Excluir

O gerenciamento de filas no RabbitMQ parece simples até que você esteja fazendo isso durante um incidente. Uma fila tem um nome, um host virtual, argumentos, consumidores, bindings, mensagens e, às vezes, políticas aplicadas sobre ela. Excluir a fila errada ou declará-la com as propriedades erradas pode quebrar uma aplicação tão rapidamente quanto uma falha no broker.

Os comandos abaixo focam no trabalho diário: declarar uma fila quando você precisa preparar a infraestrutura, listar filas quando você precisa entender o estado do broker e excluir ou limpar filas quando você intencionalmente quer remover algo. Os exemplos usam rabbitmqctl, mas a mesma cautela se aplica se você usar a UI de gerenciamento ou a API HTTP.

---

Pré-requisitos e a Ferramenta rabbitmqctl

Para executar os comandos descritos neste artigo, você deve ter acesso à linha de comando em uma máquina onde as ferramentas de gerenciamento do RabbitMQ estão instaladas, ou onde rabbitmqctl possa se conectar ao cluster de destino. Permissões são tipicamente necessárias para realizar essas operações administrativas.

A sintaxe geral para comandos rabbitmqctl é:

rabbitmqctl <comando> [argumentos]

Todos os exemplos abaixo assumem o host virtual padrão (/). Se a fila estiver em outro vhost, adicione -p <nome_do_vhost>. Isso é importante porque orders em /prod e orders em /staging são filas diferentes.

1. Declarando Novas Filas (declare_queue)

A declaração de fila é o processo de criar uma fila no broker. Embora as filas sejam geralmente declaradas pelas aplicações cliente na conexão, a declaração administrativa via rabbitmqctl é útil para configuração, teste ou definição de filas altamente específicas antes que as conexões do cliente sejam estabelecidas.

O comando declare_queue permite definir propriedades essenciais da fila, como durabilidade, exclusividade e exclusão automática.

Declaração Básica de Fila

O comando mais simples declara uma fila com configurações padrão. Na sintaxe atual da CLI do RabbitMQ, as propriedades da fila são passadas como pares chave-valor:

rabbitmqctl declare_queue name=minha_nova_fila durable=false

Definindo Propriedades da Fila

Parâmetros chave são usados para controlar a persistência e o ciclo de vida da fila:

Parâmetro	Descrição	Padrão	Justificativa
durable	Se true, a definição da fila persiste após reinicializações do broker.	false	Crítico para filas que devem sobreviver a falhas do sistema.
exclusive	Se true, a fila só pode ser consumida pela conexão declarante e é excluída quando essa conexão é fechada.	false	Usado para recursos temporários e privados.
auto_delete	Se true, a fila é excluída quando o último consumidor se desconecta.	false	Útil para filas efêmeras e de curta duração.

Exemplo: Declarando uma Fila Durável

Uma definição de fila durável sobrevive à reinicialização do broker. A sobrevivência da mensagem também depende do modo de entrega da mensagem e do comportamento de armazenamento, portanto, não trate uma fila durável como garantia de que toda mensagem é persistente.

rabbitmqctl declare_queue name=fila_duravel_producao durable=true

Exemplo: Declarando uma Fila Temporária com Exclusão Automática

rabbitmqctl declare_queue name=fila_temporaria_trabalho auto_delete=true

Dica: Se a fila já existir, declare_queue terá sucesso apenas se as propriedades especificadas corresponderem às propriedades da fila existente. Se as propriedades diferirem, o comando falhará, evitando configuração incorreta acidental.

Essa falha é útil. Se uma aplicação espera uma fila de quorum durável e um operador acidentalmente declara uma fila clássica transitória com o mesmo nome, o RabbitMQ deve rejeitar a incompatibilidade em vez de alterar silenciosamente a semântica.

2. Listando e Inspecionando Filas (list_queues)

Monitorar o status das filas é uma tarefa administrativa frequente. O comando list_queues é altamente flexível, permitindo especificar exatamente quais métricas você precisa ver, evitando sobrecarga de informações.

Listagem Básica

Por padrão, list_queues mostra colunas comuns como nome da fila, total de mensagens e consumidores. Para trabalhos operacionais, é melhor solicitar as colunas exatas que você precisa.

rabbitmqctl list_queues

Exemplo de Saída:

Timeout: 60.0 seconds...
Listing queues for vhost /
name    messages    consumers
minha_nova_fila	0	1
fila_duravel_producao	150	2

Listando Propriedades Específicas da Fila

Para obter insights operacionais mais profundos, você pode especificar uma lista separada por espaços de nomes de colunas. Isso é crucial para solucionar altas contagens de mensagens ou uso de memória.

Colunas Essenciais para Monitoramento:

Nome da Coluna	Descrição
messages_ready	Mensagens disponíveis para entrega (prontas para serem consumidas).
messages_unacknowledged	Mensagens entregues, mas ainda não confirmadas por um consumidor.
consumers	O número de consumidores ativos conectados à fila.
memory	Uso estimado de memória da fila no nó (em bytes).
policy	O nome de qualquer política aplicada à fila.
state	O estado operacional da fila (ex.: running, flow, idle).
type	Tipo de fila, como clássica ou quorum, em versões do RabbitMQ que o expõem.

Exemplo: Inspeção Detalhada da Fila

Para verificar o backlog atual, a saúde do consumidor e a aplicação de políticas, use:

rabbitmqctl list_queues name messages_ready messages_unacknowledged consumers memory policy

Leia os números juntos. Uma fila com messages_ready alta e zero consumidores geralmente significa que nenhum consumidor está conectado. Uma fila com poucas mensagens prontas, mas messages_unacknowledged alta, aponta para consumidores que receberam mensagens, mas não as estão confirmando. Isso pode ser trabalho lento, workers com falha, um prefetch count superdimensionado ou um bug que nunca chama ack/nack.

Listando Filas em um Host Virtual Específico

Se você precisar verificar filas fora do host virtual padrão, use a flag -p.

rabbitmqctl list_queues -p /api_vhost name messages consumers

3. Excluindo e Limpando Filas (delete_queue e purge_queue)

Quando uma fila é descontinuada ou precisa ser redefinida, você tem duas opções principais: excluir toda a estrutura da fila ou limpar seu conteúdo mantendo a estrutura intacta.

Excluindo uma Fila (delete_queue)

O comando delete_queue remove permanentemente a fila e todas as mensagens atualmente armazenadas nela. Esta ação é irreversível.

rabbitmqctl delete_queue minha_fila_antiga

Aviso: Risco de Perda de Dados Sempre confirme que a fila está vazia ou que seu conteúdo não é mais necessário antes da execução. Excluir uma fila com mensagens pendentes resulta em perda de dados imediata e permanente para essas mensagens.

Limpando o Conteúdo da Fila (purge_queue)

Se a estrutura da fila (bindings, durabilidade, políticas) deve permanecer, mas você precisa limpar todas as mensagens (por exemplo, para limpar um backlog de trabalhos errôneos), use purge_queue.

rabbitmqctl purge_queue minha_fila_travada

Este comando remove mensagens prontas da fila sem excluir a definição da fila. Mensagens já entregues aos consumidores e aguardando confirmação não são simplesmente apagadas por um purge. Se esses consumidores desconectarem ou rejeitarem mensagens com reenfileiramento ativado, algumas mensagens podem reaparecer. Durante uma limpeza séria, pare ou drene os consumidores primeiro para saber o que você está limpando.

Manipulando Filas em Diferentes VHosts

Para garantir que você exclua ou limpe a fila correta, sempre especifique o host virtual se a fila não estiver no contexto padrão.

# Excluindo uma fila em um host virtual específico
rabbitmqctl delete_queue -p /testing_vhost fila_teste_temporaria

Antes de excluir, geralmente executo:

rabbitmqctl list_queues -p /testing_vhost name messages_ready messages_unacknowledged consumers

Essa única verificação pega muitos erros: vhost errado, consumidores inesperados ou uma fila que ainda tem trabalho em andamento.

Resumo dos Comandos Essenciais

Esta tabela resume os comandos principais de gerenciamento de filas usados nas operações diárias do RabbitMQ:

Ação	Comando	Propósito
Declaração	rabbitmqctl declare_queue name=F durable=true	Cria uma nova fila com propriedades definidas.
Inspeção	rabbitmqctl list_queues name messages consumers	Lista filas e métricas operacionais específicas.
Exclusão	rabbitmqctl delete_queue F	Remove permanentemente a fila e suas mensagens prontas.
Limpeza	rabbitmqctl purge_queue F	Limpa mensagens prontas de uma fila mantendo a estrutura.

O hábito seguro é simples: sempre inclua o vhost quando houver qualquer dúvida, inspecione antes de comandos destrutivos e lembre-se de que a declaração de fila faz parte do contrato da sua aplicação. O tipo de fila, durabilidade, comportamento de exclusão automática e argumentos devem ser tratados como esquema, não como um detalhe casual de tempo de execução.