El dead-lettering es el mecanismo con el que RabbitMQ traslada un mensaje que ya no puede entregar a un lugar donde usted pueda ocuparse de él. Bien configurado, convierte un payload defectuoso en un ticket. Mal configurado, es la forma más habitual en que vemos desaparecer mensajes de producción sin dejar rastro. Esta guía explica el mecanismo tal como se comporta en RabbitMQ 3.13 y 4.x, los patrones de reintento que se construyen sobre él y los hábitos operativos que mantienen una dead letter queue bajo control.
Qué es exactamente el dead-lettering
Una cola envía un mensaje a dead-letter exactamente por cuatro motivos:
Un consumidor lo rechazó con basic.reject o basic.nack y requeue=false.
Expiró su TTL por mensaje o el message-ttl de la cola.
La cola superaba su límite de max-length o max-length-bytes y descartó el mensaje de la cabeza. Es el comportamiento de overflow por defecto, drop-head; con reject-publish, el broker rechaza la nueva publicación y no se envía nada a dead-letter.
En una cola de quórum, el mensaje volvió a la cola más veces de las que permite su delivery-limit.
El broker los registra como rejected, expired, maxlen y delivery_limit. Nada más cuenta. Una cola que expira mediante x-expires se elimina junto con su contenido. Un purge descarta los mensajes. Un mensaje que el broker no puede enrutar en el momento de la publicación tampoco va a dead-letter; de eso se encargan el flag mandatory o un alternate exchange.
Un dead letter exchange (DLX) es un exchange normal. No hay un tipo especial ni ningún flag en la declaración. Es simplemente el exchange al que una cola vuelve a publicar cuando envía un mensaje a dead-letter, con la dead-letter-routing-key de la cola si está definida y, si no, con la routing key original del mensaje. Al ser un exchange normal, puede distribuir los mensajes a una cola de aparcamiento (parking lot) y a una cola de auditoría, enrutarlos por su clave original mediante un topic exchange o enviar los fallos de cada equipo a su propia cola. Una «dead letter queue» es simplemente la cola que haya vinculado a él.
Al volver a publicarse, el mensaje cambia en dos aspectos. Se borra la propiedad expiration, para que un mensaje que ya expiró una vez no vuelva a expirar de inmediato; el valor original se conserva en x-death como original-expiration. Y se añade o actualiza la cabecera x-death. El cuerpo, el message id, el correlation id y todas las demás propiedades se mantienen intactos.
Configurar el dead letter exchange: argumentos frente a políticas
Hay dos formas de asociar un DLX a una cola. Los argumentos de cola los fija el cliente en el momento de la declaración:
Las políticas definen el mismo comportamiento desde el lado del broker con las claves dead-letter-exchange y dead-letter-routing-key, y se asocian a las colas mediante un patrón de nombre.
Use políticas. Los argumentos de cola son inmutables: para cambiar un DLX definido como argumento hay que eliminar la cola y volver a declararla, lo que obliga a vaciarla primero y a coordinar a todos los clientes que la declaran. Las políticas se cambian en caliente, se aplican a todas las colas que coinciden, se incluyen en las exportaciones de definitions y están en un único lugar que cualquier operador puede consultar. Cuando existen ambos, prevalece el argumento, y esa es la segunda razón para evitarlos: una aplicación que fija x-dead-letter-exchange impone un valor que operaciones no puede cambiar sin un despliegue. La excepción es x-queue-type, que tiene que ser un argumento, y no pasa nada, porque el tipo de una cola nunca cambia.
Una trampa: a una cola solo se le aplica una política, la coincidencia con mayor prioridad. Si define una política para el dead-lettering y otra para max-length o delivery-limit sobre las mismas colas, solo una surtirá efecto. Ponga todas las claves que necesita una cola en la misma definición de política.
Cuando el broker envía un mensaje a dead-letter, añade una entrada a la cabecera x-death, un array con una entrada por cada par cola-motivo. Si la misma cola vuelve a enviar el mismo mensaje a dead-letter por el mismo motivo, el count de esa entrada se incrementa y la entrada pasa al principio del array. Cada entrada registra la cola, el motivo, el exchange y las routing keys que llevaba el mensaje, una marca de tiempo y, cuando ha intervenido el TTL, original-expiration. El broker también fija x-first-death-reason, x-first-death-queue y x-first-death-exchange una sola vez, y mantiene actualizados sus equivalentes x-last-death-*. Una cabecera de ejemplo tras tres vueltas de un bucle de reintentos:
El dead-lettering puede formar un ciclo, y el broker aplica una regla para ello: si un mensaje llega dos veces a la misma cola y ningún salto del ciclo fue un rechazo, el mensaje se descarta. Si algún salto fue un rechazo del consumidor, el ciclo continúa. Por eso funcionan los bucles de reintentos basados en requeue=false, ya que cada vuelta incluye un rechazo, mientras que un bucle construido solo con TTL, como una cola de aparcamiento con un message-ttl que devuelve los mensajes por dead-letter a la cola de trabajo, descarta los mensajes en silencio en su segunda vuelta.
Las colas de quórum cambian las reglas
Las colas de quórum cuentan las reentregas en la cabecera x-delivery-count, y la clave de política delivery-limit (o el argumento x-delivery-limit) les pone un tope. Superado ese tope, la cola envía el mensaje a dead-letter si hay un DLX configurado y, si no, lo descarta. Desde RabbitMQ 4.0, el delivery limit por defecto es 20; antes era ilimitado.
Ese valor por defecto es lo que sorprende a los equipos que migran desde colas clásicas. Un consumidor que captura una excepción y llama a basic.nack con requeue=true daba vueltas indefinidamente en una cola clásica, desperdiciando CPU pero sin perder nada. En una cola de quórum de 4.x sin DLX, el mismo código descarta el mensaje tras 20 intentos, y el único rastro es un contador. Fije delivery-limit en un valor elegido por usted y combínelo siempre con un DLX.
Las colas de quórum también admiten dos estrategias de dead-lettering mediante la clave de política dead-letter-strategy. La estrategia por defecto, at-most-once, vuelve a publicar sin confirmación. Si el DLX no existe, o la cola de destino no está disponible o rechaza el mensaje, este se pierde. Es la garantía que siempre han tenido las colas clásicas.
at-least-once mantiene el mensaje enviado a dead-letter en la cola de origen hasta que todas las colas vinculadas al DLX lo han confirmado. Requiere que la cola de origen sea de quórum, que overflow sea reject-publish y que exista un DLX. Internamente, el líder de la cola ejecuta un proceso de dead-lettering, que la documentación llama dead-letter consumer: lee de la cola de origen los mensajes enviados a dead-letter, los publica en el DLX con confirms y reintenta todo lo que no se haya confirmado. De ello se derivan tres consecuencias. Si falta el DLX o el destino está caído, los mensajes se acumulan en la cola de origen y cuentan para su longitud y su disco, por diseño. Como la entrega es at-least-once, la DLQ puede recibir duplicados. Y el dead-letter consumer interno es fontanería, no su aplicación: sigue necesitando un consumidor real en la dead letter queue.
Comportamiento
Cola clásica
Cola de quórum
Límite de reentregas
Ninguno: los bucles de reencolado no terminan nunca
delivery-limit, 20 por defecto en 4.x; después, DLX o descarte
Recuento de reentregas
Solo el flag redelivered
Cabecera x-delivery-count
Estrategia de dead-lettering
Solo at-most-once
at-most-once o at-least-once
Replicación
El mirroring se eliminó en 4.0
Replicada con Raft por diseño
Overflow por defecto
drop-head
drop-head; reject-publish es obligatorio para at-least-once
Patrones de reintento que no pierden mensajes
El bucle de reintentos básico utiliza una cola de espera. El DLX de la cola de trabajo es un exchange de reintentos que enruta a una cola de espera con un message-ttl a nivel de cola y sin consumidores. El DLX de la cola de espera es el exchange de trabajo, sin dead-letter-routing-key, para que el mensaje vuelva a entrar con su routing key original. Un consumidor que sufre un fallo transitorio rechaza con requeue=false; el mensaje espera a que venza el TTL y vuelve. El consumidor lee el número de intentos en la entrada de x-death correspondiente a la cola de trabajo con motivo rejected y, al llegar al tope, mueve el mensaje a la cola de aparcamiento en lugar de volver a rechazarlo.
Para un backoff exponencial, use una cola de espera por nivel de retardo: wait.10s, wait.1m, wait.10m. No lo haga con TTL por mensaje en una sola cola. Los mensajes expirados solo se eliminan desde la cabeza de la cola, tanto en colas clásicas como de quórum, así que un mensaje de diez minutos en la cabeza bloquea a uno de diez segundos que tenga detrás. Con colas por niveles, el consumidor elige el nivel según el número de intentos, publica en el exchange de reintentos con la routing key de ese nivel, espera el publisher confirm y solo entonces confirma el original. Confirmar antes de recibir el confirm es justo donde los reintentos gestionados por el consumidor pierden mensajes. Mantenga de todos modos el DLX en la cola de trabajo como red de seguridad para delivery-limit.
La alternativa es el plugin delayed message exchange: se publica con una cabecera x-delay y el exchange retiene el mensaje hasta que transcurre el retardo. El precio es la durabilidad. Los mensajes retrasados residen en un almacén local del nodo que aloja el exchange y no se replican, así que perder ese nodo supone perder todos los mensajes pendientes, y un backlog grande de mensajes pendientes degrada el plugin. Además, no hay ninguna cola que inspeccionar. Para unos pocos retardos cortos resulta cómodo; para un backlog de reintentos que quizá tenga que examinar a las 3 de la madrugada, las colas de espera son aburridas, visibles y replicadas si se declaran como colas de quórum.
Los reintentos solo sirven para fallos transitorios. Un mensaje que falla de forma determinista, porque el payload está mal formado o hace referencia a un registro que no existe, debe ir directamente a la cola de aparcamiento, así que distinga en el consumidor las excepciones reintentables de las que no lo son. Y todos los mecanismos de esta página pueden entregar el mismo mensaje dos veces: los reintentos, los reprocesamientos y el dead-lettering at-least-once garantizan la entrega, no la unicidad. Los consumidores deben ser idempotentes, con el message id o una clave de negocio como referencia, o un reintento convertirá un fallo en un cobro duplicado.
Ejemplo práctico: procesamiento de pedidos con una cola de espera y una cola de aparcamiento
La topología:
Exchange orders (topic) con la cola de quórum orders.work vinculada a order.*.
Exchange orders.retry (fanout) con la cola de quórum orders.wait.30s, TTL de 30 segundos y dead-lettering de vuelta a orders.
Exchange orders.dlx (fanout) con la cola de quórum orders.parking, sin TTL ni automatización.
El consumidor aplica el tope de intentos y aparca de forma explícita, publicando con confirm antes de confirmar el mensaje:
MAX_ATTEMPTS = 3
def on_message(msg):
attempts = death_count(msg.headers, queue="orders.work", reason="rejected")
try:
process_order(msg) # idempotent on msg.message_id
msg.ack()
except RetryableError as err:
if attempts + 1 >= MAX_ATTEMPTS:
park(msg, reason=str(err))
else:
log.warning("retry", id=msg.message_id, attempt=attempts + 1, err=err)
msg.reject(requeue=False) # -> orders.retry -> orders.wait.30s -> orders
except NonRetryableError as err:
park(msg, reason=str(err))
def park(msg, reason):
headers = dict(msg.headers, **{"x-parked-reason": reason, "x-parked-at": now_iso()})
publish_with_confirm("orders.dlx", msg.routing_key, msg.body, msg.properties, headers)
msg.ack() # ack only after the broker confirmed the park
Cada pieza protege frente a algo concreto. Una caída a mitad del procesamiento reencola el mensaje; cinco seguidas disparan delivery-limit y el mensaje va a la cola de espera en lugar de descartarse. Un fallo transitorio espera 30 segundos y vuelve, hasta un máximo de tres intentos. Un fallo permanente se aparca a la primera. El dead-lettering at-least-once garantiza que el salto de reintento no pueda perder un mensaje aunque orders.wait.30s deje de estar disponible brevemente.
Operar una dead letter queue
Una dead letter queue solo es útil si alguien se entera de cuándo se llena. Cuatro señales cubren casi todo.
Profundidad: rabbitmq_queue_messages para la cola de aparcamiento y cada cola de espera, del plugin de Prometheus con métricas por objeto o de la familia queue_coarse_metrics del endpoint detallado. Tasa, que detecta los cambios antes que la profundidad: los contadores rabbitmq_global_messages_dead_lettered_*_total desglosan el dead-lettering por motivo y, en el caso de at-least-once, por confirmación. Número de consumidores, que indica que la topología está intacta: rabbitmq_queue_consumers debe ser distinto de cero en la cola de aparcamiento y exactamente cero en todas las colas de espera, porque un consumidor en una cola de espera anula el retardo. Antigüedad, que RabbitMQ no expone directamente; aproxímela a partir de la cabecera x-parked-at o del campo time de x-death al muestrear la cola.
Umbrales de partida, que deberá ajustar a cada servicio:
Cualquier dead-lettering en una cola que normalmente no tiene ninguno: aviso inmediato; el primero es el más barato de investigar.
Tasa de dead-lettering superior al uno por ciento de la tasa de publicación durante cinco minutos: alerta a la guardia.
Cualquier incremento del contador delivery_limit: investigar; indica consumidores que se caen o bucles de reencolado, no fallos de negocio.
Profundidad de la cola de aparcamiento por encima de una cifra acorde con su capacidad para revisar los mensajes, o en aumento continuo durante 30 minutos: alerta a la guardia.
Cero consumidores en la cola de aparcamiento durante diez minutos, o cualquier consumidor en una cola de espera: alerta.
Profundidad de la cola de origen en aumento mientras la DLQ se mantiene estable, con at-least-once configurado: el DLX o su destino están rotos.
Registre en el log, en el momento de aparcar, lo que el broker no registra: la clase y el mensaje de la excepción, el host y la build del consumidor, el message id y el correlation id, el exchange y la routing key originales que figuran en x-death, y el número de intentos. El broker sabe por qué un mensaje fue a dead-letter; solo el consumidor sabe qué falló. Añada también el motivo como cabecera, como hace el ejemplo con x-parked-reason, para que quien abra la cola más adelante pueda leerlo sin cruzar datos con los logs. No registre cuerpos completos salvo que sean pequeños y no contengan nada sensible. El cuerpo ya está en la cola.
Reprocesar mensajes de forma segura
Reprocesar significa volver a publicar los mensajes aparcados en el exchange de trabajo. Corrija primero la causa. Reprocesar sobre un consumidor sin corregir crea un bucle entre la cola de aparcamiento y la cola de trabajo con una persona en medio.
La herramienta más sencilla es un shovel dinámico desde la cola de aparcamiento hasta el exchange de trabajo, creado con rabbitmqctl set_parameter shovel. Use un ack-mode de on-confirm para que un mensaje salga de la cola de aparcamiento solo cuando la cola de trabajo lo haya confirmado, fije dest-exchange en el exchange de trabajo y deje dest-exchange-key sin definir para que se use la routing key original, y fije src-delete-after en queue-length para que el shovel vacíe lo que había cuando arrancó y después se elimine. La acción de mover mensajes de la interfaz de gestión es, por debajo, un shovel. Un shovel reprocesa todo en orden y sin filtrar, y x-death sigue acumulándose, que es justo lo que se busca: un mensaje que vuelve a fallar regresa a la cola de aparcamiento con un historial más largo.
Cuando necesite seleccionar, use un consumidor de reprocesamiento: una pequeña herramienta que consume de la cola de aparcamiento con un prefetch moderado, filtra por cabecera, fecha o id, publica con confirms y confirma cada mensaje tras su confirm. Limite su ritmo, porque una cola de aparcamiento que se ha llenado durante el fin de semana puede desbordar una base de datos aguas abajo el lunes por la mañana. Si quiere que el recuento de intentos empiece de cero, puede eliminar x-death, pero debería registrar en su lugar una cabecera x-replay-count.
No vuelva a publicar desde un script improvisado sin confirms, no reprocese en horas punta y no reprocese un lote cuya causa raíz no haya identificado.
Retención y disco
Una cola de aparcamiento es estado duradero. En una cola de quórum, cada mensaje se escribe en el log de Raft y en los ficheros de segmento de todos los miembros, así que una cola de tres miembros guarda tres copias durante todo el tiempo que el mensaje permanezca en ella. Los mensajes que van a dead-letter suelen ser los grandes, y suelen quedarse días. Planifique el disco.
Limite la cola de aparcamiento con max-length-bytes y con overflow en reject-publish, no en drop-head. drop-head descarta en silencio la evidencia más antigua cuando la cola se llena. reject-publish hace que una cola de aparcamiento llena se note: el dead-lettering hacia ella falla, la cola de origen at-least-once retiene su backlog y sus alertas saltan. Que se note es lo correcto.
No configure message-ttl en la cola de aparcamiento. La retención corresponde a un consumidor de archivado que mueva los mensajes más antiguos que su ventana de revisión a almacenamiento de objetos o a una tabla de base de datos y los confirme, para que la cola siga siendo una bandeja de entrada y no un archivo. El fallo que se evita es real: una cola de aparcamiento que nadie vacía crece hasta que el nodo cruza el umbral de la alarma de disco libre, y la alarma de disco bloquea a todos los publicadores del nodo, lo que convierte una lenta acumulación de fallos en una caída de todo el clúster.
Antipatrones que vemos en producción
Una DLQ sin consumidor y sin alertas. Los mensajes se acumulan hasta que salta la alarma de disco o alguien descubre la cola meses después durante un incidente sin relación. Si no se daría cuenta de que la cola crece, lo que ha configurado es una fuga con pasos adicionales.
Enviar a dead-letter hacia el exchange al que ya está vinculada la cola, sin cambiar la routing key. El mensaje vuelve a la misma cola. Si expiró o se descartó por longitud, la detección de ciclos lo descarta. Si fue rechazado, entra en un bucle a toda velocidad por el consumidor, satura la CPU y llena los logs.
Reintentos sin límite. Sin tope de intentos, un mensaje que nunca va a funcionar circula indefinidamente y consume capacidad de los consumidores en cada vuelta, y con at-least-once y reject-publish puede acabar atascando la cola de origen.
Colas clásicas con mirroring como destino del DLX en 4.x. El mirroring de colas clásicas se eliminó en RabbitMQ 4.0 y las claves de política ha-* ya no se respetan. Una dead letter queue que estaba replicada en 3.x se convierte tras la actualización en una cola clásica de un solo nodo, y si ese nodo falla, la evidencia se pierde con él. Convierta las dead letter queues en colas de quórum antes de actualizar.
TTL en la propia DLQ. Un message-ttl de una semana en la cola de aparcamiento «para tenerla ordenada» borra exactamente los mensajes que necesita una investigación y, si además la cola de aparcamiento devuelve los mensajes por dead-letter a la cola de trabajo, el TTL crea un ciclo de pura expiración que la detección de ciclos descarta en silencio.
Dos menores: registrar el cuerpo en el log y confirmar el mensaje en lugar de aparcarlo, lo que equivale a usar una línea de log como cola; y ejecutar el consumidor de la cola de aparcamiento en el mismo proceso que el consumidor de trabajo, de modo que el mismo fallo que llena la cola de aparcamiento tumba también lo que debía vaciarla.
Si sus dead letter queues se están llenando y no sabe por qué, o está planificando la actualización a 4.x y quiere que revisemos la topología de DLX antes de que las colas con mirroring dejen de ser una opción, a eso nos dedicamos. AceMQ es el único partner MSP de RabbitMQ designado por Broadcom, da soporte a RabbitMQ desde 3.8.x hasta 4.x y responde a los incidentes P1 con objetivos de respuesta desde 15 minutos, según el plan. Consulte nuestros planes de soporte de RabbitMQ o descubra más sobre cómo trabajamos con RabbitMQ.
Preguntas frecuentes
¿Qué diferencia hay entre un dead letter exchange y una dead letter queue?
Un dead letter exchange es el exchange al que una cola vuelve a publicar un mensaje cuando lo envía a dead-letter. Es un exchange normal, sin ningún tipo especial. Una dead letter queue es cualquier cola vinculada a ese exchange, y el nombre es una convención, no un concepto del broker. RabbitMQ solo conoce el exchange; dónde acaba el mensaje depende de los bindings que haya declarado. Esa separación es útil: un mismo DLX puede distribuir los mensajes a una cola de aparcamiento (parking lot) para reprocesarlos y a una cola de auditoría para analizarlos, o enrutar los fallos de cada equipo a su propia cola según la routing key original.
¿RabbitMQ envía a dead-letter los mensajes que no se pueden enrutar?
No. El dead-lettering solo se aplica a mensajes que ya estaban en una cola y que fueron rechazados, expiraron, se descartaron por longitud o superaron el delivery limit de una cola de quórum. Un mensaje publicado en un exchange sin ningún binding que coincida se descarta en el momento de la publicación, salvo que el publicador haya activado el flag mandatory, en cuyo caso se le devuelve, o que el exchange tenga configurado un alternate exchange, en cuyo caso se enruta allí. Si los mensajes no enrutables le importan, configure un alternate exchange con su propia cola y monitorícelo igual que una dead letter queue.
¿Cómo se cuentan los reintentos en RabbitMQ?
Lea la cabecera x-death. Cada entrada representa un par cola-motivo, y su campo count se incrementa cada vez que esa cola envía el mensaje a dead-letter por ese motivo. En un bucle de reintentos con cola de espera, busque la entrada cuyo queue sea su cola de trabajo y cuyo reason sea rejected: su count es el número de intentos realizados hasta el momento. En las colas de quórum, la cabecera independiente x-delivery-count cuenta las reentregas dentro de una misma cola, lo que recoge caídas y reencolados más que rechazos explícitos. Aplique el límite en el consumidor y, cuando se alcance, aparque el mensaje con una publicación explícita confirmada.
¿Se puede usar un dead letter exchange con colas de quórum?
Sí, y las colas de quórum añaden dos cosas que las colas clásicas nunca tuvieron. La política delivery-limit limita las reentregas y envía el mensaje a dead-letter cuando se supera, con un valor por defecto de 20 a partir de RabbitMQ 4.0, así que configure un DLX o esos mensajes se descartarán. La clave de política dead-letter-strategy puede fijarse en at-least-once, que mantiene los mensajes enviados a dead-letter en la cola de origen hasta que la cola de destino los confirma. Para ello, overflow debe ser reject-publish. Tanto la cola de origen como, idealmente, la propia dead letter queue deberían ser colas de quórum, para que la evidencia de los fallos quede replicada.
¿Qué ocurre si el dead letter exchange no existe?
El broker no valida el nombre del exchange al declarar la cola ni al aplicar la política, así que la configuración se acepta sin avisar. Con la estrategia por defecto, at-most-once, todos los mensajes enviados a dead-letter se descartan, sin ningún error ni línea de log, lo que la convierte en una de las formas más silenciosas de perder datos en RabbitMQ. Con at-least-once en una cola de quórum, los mensajes enviados a dead-letter se retienen en la cola de origen hasta que el exchange aparece y la cola de destino los confirma, de modo que lo que crece es la cola de origen. Declare el DLX y su cola en las definitions, y configure alertas ante cualquier tasa de dead-lettering que no vaya acompañada de un crecimiento de la DLQ.
¿Debo configurar un TTL en mi dead letter queue?
No. Un message-ttl en la cola de aparcamiento borra justamente los mensajes que guardó para que alguien pudiera inspeccionarlos y reprocesarlos, y los borra según un temporizador que no tiene nada que ver con si el problema de fondo se ha solucionado. Si además la cola de aparcamiento devuelve los mensajes por dead-letter a la cola de trabajo, la expiración crea un ciclo sin ningún rechazo, que el broker descarta en silencio. Gestione la retención con un consumidor de archivado que mueva los mensajes antiguos a almacenamiento duradero y los confirme, limite la cola con max-length-bytes y reject-publish, y configure alertas por profundidad y antigüedad.
Tanto si está resolviendo un incidente en producción como si planifica una migración o quiere una segunda opinión sobre su arquitectura, nuestro equipo está preparado. Sin discursos comerciales, solo respuestas.