En ocasiones los mensajes fallan: un consumidor los rechaza, se agotan los reintentos o expira el tiempo de vida (TTL). En lugar de perderlos, un exchange de dead-letter (DLX) los captura y los enruta a una cola dedicada para su inspección, reprocesamiento o generación de alertas.
A continuación se describen los conceptos clave, el proceso de enrutamiento, los métodos de configuración y los encabezados de los mensajes de dead-letter en ApsaraMQ for RabbitMQ.
Conceptos clave
|
Término |
Definición |
|
Exchange de dead-letter |
Exchange que recibe mensajes de dead-letter y los enruta a una cola de dead-letter según las claves de enlace, las claves de enrutamiento y los atributos de los encabezados. Cualquier tipo de exchange estándar (direct, fanout, topic o headers) puede funcionar como exchange de dead-letter. |
|
Clave de enrutamiento de dead-letter |
Clave de enrutamiento que se utiliza para enrutar un mensaje de dead-letter. Si no se especifica, el mensaje conserva su clave de enrutamiento original. |
|
Mensaje de dead-letter |
Mensaje reenviado a un exchange de dead-letter. Consulte Cuándo un mensaje se convierte en dead-letter para ver la lista completa de eventos que lo desencadenan. |
|
Cola de dead-letter |
Cola vinculada a un exchange de dead-letter que almacena los mensajes de dead-letter. |
Cuándo un mensaje se convierte en dead-letter
Un mensaje se envía al exchange de dead-letter cuando ocurre cualquiera de los siguientes eventos:
Acuse de recibo negativo: un consumidor llama a
basic.rejectobasic.nackconrequeueestablecido enfalse.Agotamiento de reintentos: el mensaje no se consume después de 16 intentos de reintento. Para más detalles, consulte Consumption retry policies.
Vencimiento del TTL: el mensaje permanece en la cola más tiempo del que indica su TTL configurado. Para más detalles, consulte Message TTL.
Cómo funciona
Un productor publica un mensaje en un exchange.
El exchange enruta el mensaje a una cola.
Un consumidor extrae el mensaje de la cola.
El mensaje se convierte en dead-letter por un acuse de recibo negativo, tras 16 intentos de reintento con errores o cuando vence su TTL.
La cola reenvía el mensaje de dead-letter al exchange que especifica
x-dead-letter-exchange, mediante la clave de enrutamiento que definex-dead-letter-routing-key.El exchange de dead-letter enruta el mensaje a la cola de dead-letter vinculada.
Notas de uso
Requisito de mismo vhost: el exchange de dead-letter y su cola vinculada deben residir en el mismo vhost. No es compatible el enrutamiento de dead-letter entre distintos vhosts.
Enlace inmutable del DLX: una vez que se crea una cola con un exchange de dead-letter, no se puede modificar la configuración del DLX. Elimine la cola y cree una nueva con la configuración actualizada.
Sin DLX configurado: si una cola no tiene configurado un exchange de dead-letter, los mensajes se eliminan de forma permanente cuando se supera el número máximo de intentos de entrega (16 de manera predeterminada). Si hay un exchange de dead-letter configurado, los mensajes se enrutan a la cola de dead-letter correspondiente.
Configurar un exchange de dead-letter
Configure un exchange de dead-letter desde la consola de ApsaraMQ for RabbitMQ, la API CreateQueue o un SDK de cliente.
Consola
Configure un exchange de dead-letter al crear una cola en la consola.
Inicie sesión en la consola de ApsaraMQ for RabbitMQ.
En la página Overview, dentro de la sección Resource Distribution, seleccione una región.
En la página Instances, haga clic en el nombre de la instancia de destino.
En el panel de navegación izquierdo, haga clic en Queues.
En la página Queues, seleccione un vhost en la lista desplegable Change junto a vhost y luego haga clic en Create Queue.
En el panel Create Queue, establezca los siguientes parámetros y haga clic en OK.
|
Parámetro |
Descripción |
|
Queue Name |
Nombre de la cola. Admite letras, dígitos, guiones ( |
|
Auto Delete |
Indica si se elimina automáticamente la cola después de que el último consumidor cancela la suscripción. Valores válidos: |
|
Advanced Settings |
Haga clic para expandir. Configure el exchange de dead-letter y los ajustes relacionados: |
|
- DeadLetterExchange |
Exchange que recibe los mensajes de dead-letter de esta cola. |
|
- DeadLetterRoutingKey |
Clave de enrutamiento para los mensajes de dead-letter. El exchange de dead-letter usa esta clave para enrutar los mensajes a la cola de dead-letter correspondiente. |
|
- MessageTTL |
TTL del mensaje en milisegundos. Los mensajes que no se consumen dentro de este periodo se convierten en mensajes de dead-letter y se reenvían al exchange de dead-letter. Para más detalles, consulte Message TTL. |
API
Llame a la operación CreateQueue con los parámetros del exchange de dead-letter. Para más detalles, consulte CreateQueue.
SDK de cliente
Especifique x-dead-letter-exchange y x-dead-letter-routing-key en los argumentos de la cola al declararla.
El siguiente ejemplo en Java declara un exchange de tipo direct llamado some.exchange.name como exchange de dead-letter, con demo-routing-key como clave de enrutamiento de dead-letter:
channel.exchangeDeclare("some.exchange.name", "direct");
Map<String, Object> args = new HashMap<String, Object>();
args.put("x-dead-letter-exchange", "some.exchange.name");
args.put("x-dead-letter-routing-key", "demo-routing-key");
channel.queueDeclare("MyQueue", false, false, false, args);Encabezados de los mensajes de dead-letter
Cuando un mensaje se convierte en dead-letter, ApsaraMQ for RabbitMQ agrega encabezados de metadatos para registrar el historial del evento.
Resumen de encabezados
|
Encabezado |
Descripción |
|
|
Exchange donde se encontraba el mensaje cuando se convirtió en dead-letter por primera vez. |
|
|
Cola donde se encontraba el mensaje cuando se convirtió en dead-letter por primera vez. |
|
|
Motivo por el cual el mensaje se convirtió en dead-letter por primera vez. |
|
|
Número total de veces que el mensaje se ha convertido en dead-letter. |
El arreglo x-death
El encabezado x-death es un arreglo de entradas. Cada entrada registra un evento de dead-letter con los siguientes campos:
|
Campo |
Descripción |
|
|
Motivo por el cual el mensaje se convirtió en dead-letter. |
|
|
Cola donde se encontraba el mensaje cuando se convirtió en dead-letter. |
|
|
Exchange donde se publicó el mensaje antes de convertirse en dead-letter. |
|
|
Claves de enrutamiento del mensaje en el momento en que se convirtió en dead-letter. |
|
|
Número de veces que el mensaje se convirtió en dead-letter desde esta cola por este motivo. |
|
|
Momento en que el mensaje se convirtió en dead-letter. |
Valores de motivo de dead-letter
|
Valor |
Evento desencadenante |
|
|
Venció el TTL del mensaje. |
|
|
El mensaje recibió un acuse de recibo negativo con |
|
|
El mensaje se rechazó con |
|
|
El mensaje falló después de 16 intentos de reintento. |
Habilitar el TTL para las colas de dead-letter
De manera predeterminada, los mensajes de una cola de dead-letter no caducan, incluso si la cola tiene un TTL configurado. Habilite la función de TTL a nivel de instancia para permitir que los mensajes de dead-letter respeten la configuración de TTL de la cola. Cuando vence el TTL de un mensaje de dead-letter, este se reenvía al siguiente exchange de dead-letter configurado.
Tipos de instancia compatibles
La función de TTL para las colas de dead-letter está disponible en los siguientes tipos de instancia:
Serverless
Enterprise Edition (Subscription)
Platinum Edition (Subscription)
Procedimiento
En la página Instances de la consola de ApsaraMQ for RabbitMQ, haga clic en el nombre de la instancia de destino.
En la página Instance Details, haga clic en la pestaña Limits.
Haga clic en Activate junto a TTL Feature Supported.
Evite crear bucles de enrutamiento de dead-letter. Por ejemplo, si la cola de dead-letter de la cola A es la cola B, y la de la cola B es la cola A, los mensajes circularán de forma indefinida. Si ApsaraMQ for RabbitMQ detecta un bucle de este tipo sin eventos de rechazo, deshabilita automáticamente el TTL de los mensajes afectados para detenerlo.
Un mensaje de dead-letter se puede enrutar entre colas un máximo de 16 veces. Al alcanzar este límite, se deshabilita el TTL de los mensajes afectados.
Pasos siguientes
Manage exchanges: elimine un exchange de dead-letter o vincule una cola de dead-letter a un exchange de dead-letter.
Message TTL: establezca tiempos de vencimiento en los mensajes.
Consumption retry policies: configure el comportamiento de reintento antes de que los mensajes se conviertan en dead-letter.