Comandos Esenciales de RabbitMQ para la Gestión de Colas: Declarar, Listar, Eliminar

La gestión de colas en RabbitMQ parece simple hasta que la realizas durante un incidente. Una cola tiene un nombre, un host virtual, argumentos, consumidores, enlaces, mensajes y, a veces, políticas superpuestas. Eliminar la cola incorrecta o declararla con las propiedades equivocadas puede romper una aplicación tan rápido como una caída del broker.

Los comandos a continuación se centran en el trabajo diario: declarar una cola cuando necesitas preparar infraestructura, listar colas cuando necesitas entender el estado del broker, y eliminar o purgar colas cuando deseas eliminar algo intencionalmente. Los ejemplos usan rabbitmqctl, pero la misma precaución aplica si usas la interfaz de gestión UI o la API HTTP.

---

Prerrequisitos y la Herramienta rabbitmqctl

Para ejecutar los comandos descritos en este artículo, debes tener acceso a la línea de comandos de una máquina donde las herramientas de gestión de RabbitMQ estén instaladas, o donde rabbitmqctl pueda conectarse al clúster objetivo. Generalmente se requieren permisos para realizar estas operaciones administrativas.

La sintaxis general para los comandos de rabbitmqctl es:

rabbitmqctl <comando> [argumentos]

Todos los ejemplos a continuación asumen el host virtual predeterminado (/). Si la cola está en otro vhost, agrega -p <nombre_vhost>. Esto es importante porque orders en /prod y orders en /staging son colas diferentes.

1. Declarar Nuevas Colas (declare_queue)

La declaración de colas es el proceso de crear una cola en el broker. Aunque las colas suelen ser declaradas por las aplicaciones cliente al conectarse, la declaración administrativa mediante rabbitmqctl es útil para configuración, pruebas o definición de colas muy específicas antes de que se establezcan las conexiones de los clientes.

El comando declare_queue te permite definir propiedades esenciales de la cola, como durabilidad, exclusividad y autoeliminación.

Declaración Básica de Cola

El comando más simple declara una cola con configuraciones predeterminadas. En la sintaxis actual de la CLI de RabbitMQ, las propiedades de la cola se pasan como pares clave-valor:

rabbitmqctl declare_queue name=mi_nueva_cola durable=false

Definición de Propiedades de la Cola

Los parámetros clave se utilizan para controlar la persistencia y el ciclo de vida de la cola:

Parámetro	Descripción	Predeterminado	Justificación
durable	Si es true, la definición de la cola persiste tras reinicios del broker.	false	Crítico para colas que deben sobrevivir a caídas del sistema.
exclusive	Si es true, la cola solo puede ser consumida por la conexión que la declara y se elimina cuando esa conexión se cierra.	false	Usado para recursos temporales y privados.
auto_delete	Si es true, la cola se elimina cuando el último consumidor se desconecta.	false	Útil para colas efímeras de corta duración.

Ejemplo: Declarar una Cola Duradera

Una definición de cola duradera sobrevive al reinicio del broker. La supervivencia de los mensajes también depende del modo de entrega y el comportamiento de almacenamiento, por lo que no trates una cola duradera como una garantía de que cada mensaje es persistente.

rabbitmqctl declare_queue name=cola_duradera_produccion durable=true

Ejemplo: Declarar una Cola Temporal con Autoeliminación

rabbitmqctl declare_queue name=cola_temporal_trabajo auto_delete=true

Consejo: Si la cola ya existe, declare_queue tendrá éxito solo si las propiedades especificadas coinciden con las propiedades de la cola existente. Si las propiedades difieren, el comando fallará, evitando una mala configuración accidental.

Ese fallo es útil. Si una aplicación espera una cola de quórum duradera y un operador declara accidentalmente una cola clásica transitoria con el mismo nombre, RabbitMQ debería rechazar la discrepancia en lugar de cambiar silenciosamente la semántica.

2. Listar e Inspeccionar Colas (list_queues)

Monitorear el estado de las colas es una tarea administrativa frecuente. El comando list_queues es altamente flexible, permitiéndote especificar exactamente qué métricas necesitas ver, evitando la sobrecarga de información.

Listado Básico

Por defecto, list_queues muestra columnas comunes como nombre de la cola, mensajes totales y consumidores. Para trabajos operativos, es mejor solicitar las columnas exactas que necesitas.

rabbitmqctl list_queues

Ejemplo de Salida:

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

Listado de Propiedades Específicas de la Cola

Para obtener información operativa más profunda, puedes especificar una lista de nombres de columnas separados por espacios. Esto es crucial para solucionar problemas de altos recuentos de mensajes o uso de memoria.

Columnas Esenciales para el Monitoreo:

Nombre de Columna	Descripción
messages_ready	Mensajes disponibles para entrega (listos para ser consumidos).
messages_unacknowledged	Mensajes entregados pero no reconocidos por un consumidor.
consumers	El número de consumidores activos conectados a la cola.
memory	Uso estimado de memoria de la cola en el nodo (en bytes).
policy	El nombre de cualquier política aplicada a la cola.
state	El estado operativo de la cola (ej., running, flow, idle).
type	Tipo de cola, como clásica o quórum, en versiones de RabbitMQ que lo exponen.

Ejemplo: Inspección Detallada de la Cola

Para verificar el backlog actual, la salud del consumidor y la aplicación de políticas, usa:

rabbitmqctl list_queues name messages_ready messages_unacknowledged consumers memory policy

Lee los números juntos. Una cola con alta messages_ready y cero consumidores generalmente significa que no hay consumidor conectado. Una cola con pocos mensajes listos pero alta messages_unacknowledged apunta a consumidores que han recibido mensajes pero no los están reconociendo. Eso podría ser trabajo lento, trabajadores caídos, un tamaño de prefetch excesivo o un error que nunca llama ack/nack.

Listado de Colas en un Host Virtual Específico

Si necesitas verificar colas fuera del host virtual predeterminado, usa la bandera -p.

rabbitmqctl list_queues -p /api_vhost name messages consumers

3. Eliminar y Purgar Colas (delete_queue y purge_queue)

Cuando una cola está obsoleta o necesita ser reiniciada, tienes dos opciones principales: eliminar toda la estructura de la cola, o purgar su contenido manteniendo la estructura intacta.

Eliminar una Cola (delete_queue)

El comando delete_queue elimina permanentemente la cola y todos los mensajes almacenados actualmente en ella. Esta acción es irreversible.

rabbitmqctl delete_queue mi_cola_vieja

Advertencia: Riesgo de Pérdida de Datos Siempre confirma que la cola está vacía o que su contenido ya no es necesario antes de ejecutarlo. Eliminar una cola con mensajes pendientes resulta en una pérdida de datos inmediata y permanente para esos mensajes.

Purgar el Contenido de una Cola (purge_queue)

Si la estructura de la cola (enlaces, durabilidad, políticas) debe permanecer, pero necesitas borrar todos los mensajes (ej., para limpiar un backlog de trabajos erróneos), usa purge_queue.

rabbitmqctl purge_queue mi_cola_atascada

Este comando elimina los mensajes listos de la cola sin eliminar la definición de la cola. Los mensajes ya entregados a los consumidores y que esperan reconocimiento no se borran simplemente con un purge. Si esos consumidores se desconectan o rechazan mensajes con reencolado habilitado, algunos mensajes pueden reaparecer. Durante una limpieza seria, detén o drena a los consumidores primero para saber qué estás purgando.

Manejo de Colas en Diferentes VHosts

Para asegurarte de eliminar o purgar la cola correcta, siempre especifica el host virtual si la cola no está en el contexto predeterminado.

# Eliminar una cola en un host virtual específico
rabbitmqctl delete_queue -p /testing_vhost cola_prueba_temporal

Antes de eliminar, suelo ejecutar:

rabbitmqctl list_queues -p /testing_vhost name messages_ready messages_unacknowledged consumers

Esa única verificación atrapa muchos errores: vhost incorrecto, consumidores inesperados o una cola que aún tiene trabajo en curso.

Resumen de Comandos Esenciales

Esta tabla resume los comandos principales de gestión de colas utilizados en las operaciones diarias de RabbitMQ:

Acción	Comando	Propósito
Declaración	rabbitmqctl declare_queue name=Q durable=true	Crea una nueva cola con propiedades definidas.
Inspección	rabbitmqctl list_queues name messages consumers	Lista colas y métricas operativas específicas.
Eliminación	rabbitmqctl delete_queue Q	Elimina permanentemente la cola y sus mensajes listos.
Limpieza	rabbitmqctl purge_queue Q	Limpia los mensajes listos de una cola manteniendo la estructura.

El hábito seguro es simple: siempre incluye el vhost cuando haya alguna duda, inspecciona antes de comandos destructivos, y recuerda que la declaración de colas es parte del contrato de tu aplicación. El tipo de cola, la durabilidad, el comportamiento de autoeliminación y los argumentos deben tratarse como un esquema, no como un detalle casual de tiempo de ejecución.