Praktický návod

Jak funguje dead-letter queue a kdy ji použít

Trvale neúspěšnou zprávu odděl od běžného provozu, zachovej důvod chyby a vrať ji až po opravě příčiny.

20 minut · RabbitMQ

Nejdřív stručně

DLQ není nekonečný retry

RabbitMQ nepřesouvá zprávu přímo do speciální fronty. Zdrojová fronta ji dead-letteruje do běžného dead-letter exchange a binding ji teprve doručí do fronty určené k analýze.

Zpráva se může dead-letterovat po reject nebo nack bez requeue, po expiraci TTL, překročení délky fronty nebo delivery limitu quorum fronty. DLQ uchovává problém; sama ho neopravuje.

Připrav si

Co budeš potřebovat

Nejdřív rozliš dočasnou a trvalou chybu. Jinak DLQ pouze schová neomezenou retry smyčku.

Zdrojovou frontu, stabilní routing key a popsaný formát zprávy včetně message ID a verze schématu.
Taxonomii chyb: dočasná závislost, neplatná data, nepodporovaná verze a neznámá chyba.
Limit pokusů a prodlužující se čekání mimo hlavní frontu.
Vlastníka alertu, retenční pravidla, bezpečný nástroj pro inspekci a řízený replay.

Kroky 1 až 3

Navrhni cestu zprávy po selhání

Hlavní fronta má zůstat průchozí. Jedna poison message nesmí donekonečna zabírat stejného consumera.

1. Vytvoř dead-letter exchange a cílovou frontu

Deklaruj samostatný exchange, například orders.dlx, a durable frontu orders.failed s bindingem pro zamýšlené routing keys.
Zdrojové frontě nastav dead-letter-exchange a případně dead-letter-routing-key. Preferuj RabbitMQ policy, kterou lze změnit bez redeklarace fronty.
Ověř, že cílový exchange i binding existují. Nezpracovatelná nebo neroutovatelná dead-letter zpráva se nesmí tiše ztratit.
Nastav limit délky nebo retenci DLQ a sleduj disk. DLQ není bezedný archiv ani náhrada zálohy.

rabbitmqctl set_policy orders-dlx "^orders$" '{"dead-letter-exchange":"orders.dlx"}' --apply-to queues

Oficiální RabbitMQ dokumentace k dead lettering

2. Odděl retry od trvalého selhání

Dočasnou chybu pošli do omezené retry cesty s čekáním a následným návratem. Nack s requeue=true bez pauzy vytváří horkou smyčku.
Neplatná data nebo nepodporovanou verzi odmítni bez requeue rovnou do DLQ. Další pokus se stejným vstupem nic nezmění.
U quorum front nastav delivery-limit explicitně policy a nakonfiguruj DLX. Nespoléhej na nekonečné doručování poison message.
Zachovej původní message ID, correlation ID a bezpečný důvod chyby. Do hlaviček ani logu nekopíruj tajemství a celé osobní údaje.

transient → delayed retry → source; permanent → nack(requeue=false) → DLX

Oficiální dokumentace k poison message handling

3. Připrav inspekci a řízený replay

Alertuj na první zprávu i na tempo růstu DLQ. Čekání na zaplnění disku je pozdě.
Nástroj má zobrazit důvod dead-letteringu, stáří, typ a bezpečný výřez payloadu. Přístup audituj a omez podle citlivosti dat.
Před replayem oprav kód nebo data a vyber konkrétní zprávy. Nepřelévej automaticky celou DLQ zpět do hlavní fronty.
Replay publikuj jako novou doručovací operaci, ale zachovej původní business identitu. Consumer musí být idempotentní.

app:messages:replay --queue=orders.failed --message-id=...

Oficiální RabbitMQ reliability guide

Krok 4

Otestuj každou cestu selhání

Nestačí ručně poslat jednu zprávu do failed queue. Ověř routing, metadata, alert i návrat po opravě.

Odmítni trvale chybnou zprávu

Consumer ji musí nacknout bez requeue, zpráva se objeví právě jednou v cílové DLQ a hlavní fronta pokračuje.
Vyčerpej retry limit

Dočasnou chybu nech projít naplánovanými prodlevami. Po posledním pokusu musí skončit v DLQ, ne v nekonečné smyčce.
Oprav a přehraj jednu zprávu

Po replayi ověř obchodní výsledek právě jednou, acknowledgement a odstranění nebo označení původní DLQ položky.

Když to zlobí

Nejčastější chyby

Zpráva po nack zmizela

Zkontroluj requeue=false, nastavení DLX, oprávnění, binding a routing key. Samotný název failed queue zdrojové frontě nestačí.

rabbitmqctl list_queues name arguments

Consumer zpracovává stejnou chybu bez pauzy

Nepoužívej okamžité requeue=true pro opakovanou závislost. Zaveď omezené retry fronty s čekáním nebo jiný plánovač.

DLQ nepozorovaně roste

Přidej alert na počet, stáří nejstarší zprávy a rychlost přírůstku. Každý typ zprávy musí mít provozního vlastníka.

Hromadný replay znovu shodil službu

Přehrávej po malých dávkách s rate limitem a stop podmínkou. Nejdřív ověř jednu zprávu a opravenou příčinu.

Hotovo

Neúspěšné zprávy mají řízenou cestu.

Fronta zpráv už není blokovaná poison message. Retry má limit, DLQ má monitoring a návrat probíhá až po opravě a bezpečném výběru.

Přečíst frontu zpráv ve slovníku Všechny návody