Às vezes, as mensagens falham: um consumidor as rejeita, as tentativas se esgotam ou o tempo de vida (TTL) expira. Em vez de perder essas mensagens, um exchange de dead-letter (DLX) as captura e as encaminha para uma fila dedicada para inspeção, reprocessamento ou alertas.
As seções a seguir abordam os principais conceitos, o processo de roteamento, os métodos de configuração e os cabeçalhos das mensagens de dead-letter do ApsaraMQ for RabbitMQ.
Conceitos principais
|
Termo |
Definição |
|
Exchange de dead-letter |
Um exchange que recebe mensagens de dead-letter e as roteia para uma fila de dead-letter com base em binding keys, routing keys e atributos de cabeçalho. Qualquer tipo padrão de exchange -- direct, fanout, topic ou headers -- pode atuar como um exchange de dead-letter. |
|
Dead-letter routing key |
A routing key usada para rotear uma mensagem de dead-letter. Se não for especificada, a mensagem mantém sua routing key original. |
|
Mensagem de dead-letter |
Uma mensagem encaminhada para um exchange de dead-letter. Consulte Quando as mensagens se tornam dead-letter para ver a lista completa de gatilhos. |
|
Fila de dead-letter |
Uma fila vinculada a um exchange de dead-letter que armazena mensagens de dead-letter. |
Quando as mensagens se tornam dead-letter
A mensagem é encaminhada ao exchange de dead-letter quando ocorre qualquer uma das seguintes situações:
Confirmação negativa -- Um consumidor chama
basic.rejectoubasic.nackcomrequeuedefinido comofalse.Esgotamento de tentativas -- A mensagem não é consumida após 16 tentativas de reprocessamento. Para mais detalhes, consulte Consumption retry policies.
Expiração do TTL -- A mensagem permanece na fila por mais tempo do que o seu TTL configurado. Para mais detalhes, consulte Message TTL.
Como funciona
Um produtor publica uma mensagem em um exchange.
O exchange roteia a mensagem para uma fila.
Um consumidor busca a mensagem na fila.
A mensagem se torna dead-letter por meio de uma confirmação negativa, após 16 tentativas com falha, ou quando seu TTL expira.
A fila encaminha a mensagem de dead-letter para o exchange especificado por
x-dead-letter-exchange, usando a routing key especificada porx-dead-letter-routing-key.O exchange de dead-letter roteia a mensagem para a fila de dead-letter vinculada.
Notas de uso
Requisito de mesmo vhost -- O exchange de dead-letter e sua fila vinculada devem residir no mesmo vhost. Não há suporte para roteamento de dead-letter entre vhosts.
Vinculação imutável do DLX -- Depois de criar uma fila com um exchange de dead-letter, não é possível alterar a configuração do DLX. Exclua a fila e crie uma nova com a configuração atualizada.
DLX não configurado -- Se uma fila não tiver um exchange de dead-letter configurado, as mensagens serão excluídas permanentemente após o número máximo de tentativas de entrega (16 por padrão) ser excedido. Se um exchange de dead-letter estiver configurado, as mensagens serão roteadas para a fila de dead-letter correspondente.
Configure um exchange de dead-letter
Configure um exchange de dead-letter por meio do console do ApsaraMQ for RabbitMQ, da API CreateQueue ou de um SDK de cliente.
Console
Configure um exchange de dead-letter ao criar uma fila no console.
Faça login no console do ApsaraMQ for RabbitMQ.
Na página Overview, na seção Resource Distribution, selecione uma região.
Na página Instances, clique no nome da instância desejada.
No painel de navegação à esquerda, clique em Queues.
Na página Queues, selecione um vhost na lista suspensa Change ao lado de vhost e, em seguida, clique em Create Queue.
No painel Create Queue, defina os seguintes parâmetros e clique em OK.
|
Parâmetro |
Descrição |
|
Queue Name |
O nome da fila. Aceita letras, dígitos, hifens ( |
|
Auto Delete |
Indica se a fila deve ser excluída automaticamente após o último consumidor cancelar a inscrição. Valores válidos: |
|
Advanced Settings |
Clique para expandir. Configure o exchange de dead-letter e as configurações relacionadas: |
|
- DeadLetterExchange |
O exchange que recebe mensagens de dead-letter desta fila. |
|
- DeadLetterRoutingKey |
A routing key para mensagens de dead-letter. O exchange de dead-letter usa essa chave para rotear mensagens para a fila de dead-letter correspondente. |
|
- MessageTTL |
O TTL da mensagem em milissegundos. As mensagens não consumidas dentro desse período se tornam mensagens de dead-letter e são encaminhadas para o exchange de dead-letter. Para mais detalhes, consulte Message TTL. |
API
Chame a operação CreateQueue com os parâmetros do exchange de dead-letter. Para mais detalhes, consulte CreateQueue.
Client SDK
Especifique x-dead-letter-exchange e x-dead-letter-routing-key nos argumentos da fila ao declará-la.
O exemplo Java a seguir declara um exchange do tipo direct chamado some.exchange.name como o exchange de dead-letter, com demo-routing-key como a routing key 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);Cabeçalhos das mensagens de dead-letter
Quando uma mensagem se torna dead-letter, o ApsaraMQ for RabbitMQ adiciona cabeçalhos de metadados para rastrear o histórico do evento.
Cabeçalhos de resumo
|
Cabeçalho |
Descrição |
|
|
O exchange em que a mensagem estava quando se tornou dead-letter pela primeira vez. |
|
|
A fila em que a mensagem estava quando se tornou dead-letter pela primeira vez. |
|
|
O motivo pelo qual a mensagem se tornou dead-letter pela primeira vez. |
|
|
O número total de vezes que a mensagem se tornou dead-letter. |
O array x-death
O cabeçalho x-death é um array de entradas, e cada uma registra um evento de dead-letter com os seguintes campos:
|
Campo |
Descrição |
|
|
O motivo pelo qual a mensagem se tornou dead-letter. |
|
|
A fila em que a mensagem estava quando se tornou dead-letter. |
|
|
O exchange no qual a mensagem foi publicada antes de se tornar dead-letter. |
|
|
As routing keys da mensagem no momento em que se tornou dead-letter. |
|
|
Quantas vezes a mensagem se tornou dead-letter a partir desta fila por este motivo. |
|
|
Quando a mensagem se tornou dead-letter. |
Valores dos motivos de dead-letter
|
Valor |
Gatilho |
|
|
O TTL da mensagem expirou. |
|
|
A mensagem recebeu uma confirmação negativa com |
|
|
A mensagem foi rejeitada com |
|
|
A mensagem falhou após 16 tentativas. |
Ative o TTL para filas de dead-letter
Por padrão, as mensagens em uma fila de dead-letter não expiram, mesmo que a fila tenha um TTL configurado. Ative o recurso de TTL no nível da instância para permitir que as mensagens de dead-letter respeitem a configuração de TTL da fila. Quando o TTL de uma mensagem de dead-letter expira, ela é encaminhada para o próximo exchange de dead-letter configurado.
Tipos de instância com suporte
O recurso de TTL para filas de dead-letter está disponível nos seguintes tipos de instância:
Serverless
Enterprise Edition (Subscription)
Platinum Edition (Subscription)
Procedimento
Na página Instances do console do ApsaraMQ for RabbitMQ, clique no nome da instância desejada.
Na página Instance Details, clique na aba Limits.
Clique em Activate ao lado de TTL Feature Supported.
Evite criar loops de roteamento de dead-letter. Por exemplo, se a fila de dead-letter da Fila A for a Fila B e a fila de dead-letter da Fila B for a Fila A, as mensagens entrarão em um loop infinito. Se o ApsaraMQ for RabbitMQ detectar esse tipo de loop sem nenhum evento de rejeição, ele desativará automaticamente o TTL para as mensagens afetadas a fim de interromper o loop.
Uma mensagem de dead-letter pode ser roteada entre filas no máximo 16 vezes. Após atingir esse limite, o TTL é desativado para as mensagens afetadas.
Próximos passos
Gerencie exchanges -- Exclua um exchange de dead-letter ou vincule uma fila de dead-letter a um exchange de dead-letter.
Message TTL -- Defina tempos de expiração nas mensagens.
Consumption retry policies -- Configure o comportamento de novas tentativas antes que as mensagens se tornem dead-letter.