On this page
死信處理(dead-lettering)是 RabbitMQ 把無法再投遞的訊息,移到一個您能處理它的地方的機制。設定得當,壞掉的 payload 會變成一張待處理的工單;設定不當,這正是我們在正式環境中最常看到訊息無聲無息消失的原因。本指南說明這套機制在 RabbitMQ 3.13 與 4.x 上的實際行為、以它為基礎的重試模式,以及讓死信佇列名實相符的維運習慣。
死信處理的精確定義
佇列只會因為以下四種原因把訊息送入死信:
- 消費者以
basic.reject或basic.nack並搭配requeue=false拒絕了訊息。 - 訊息本身的 TTL,或佇列的
message-ttl到期。 - 佇列超過
max-length或max-length-bytes上限,從佇列前端捨棄了訊息。這是預設的drop-head溢位行為;若使用reject-publish,訊息代理會改為拒絕新的發布,不會有任何訊息被送入死信。 - 在仲裁佇列上,訊息被退回佇列的次數超過其
delivery-limit的允許值。
訊息代理會分別記錄為 rejected、expired、maxlen 與 delivery_limit。除此之外都不算。透過 x-expires 過期的佇列,會連同內容一起被刪除;清空(purge)會直接捨棄訊息;訊息代理在發布當下無法路由的訊息也不會被送入死信,那是 mandatory 旗標或 alternate exchange 的職責。
死信交換器(DLX)就是一般的 exchange,沒有特殊類型,宣告時也沒有任何旗標。它只是佇列在送入死信時重新發布訊息的 exchange:若佇列設定了 dead-letter-routing-key 就使用它,否則沿用訊息原本的 routing key。正因為它很普通,您可以扇出到停放佇列與稽核佇列、透過 topic exchange 依原始 routing key 路由,或把各團隊的失敗訊息送到各自的佇列。所謂「死信佇列」,就只是您綁定到它的那個佇列。
訊息在重新發布時有兩處會改變。expiration 屬性會被清除,因此已經逾期一次的訊息不會馬上再次逾期;原始值會以 original-expiration 保留在 x-death 中。此外 x-death 標頭會被新增或更新。訊息本體、message id、correlation id 以及其他所有屬性都會完整保留。
設定死信交換器:佇列參數與政策的比較
將 DLX 掛到佇列上有兩種方式。佇列參數由用戶端在宣告時設定:
{
"x-queue-type": "quorum",
"x-dead-letter-exchange": "orders.retry",
"x-dead-letter-routing-key": "order.failed"
}政策則是從訊息代理端,以 dead-letter-exchange 與 dead-letter-routing-key 這兩個鍵設定相同的行為,並依名稱模式比對套用到佇列。
建議優先使用政策。佇列參數無法變更:要修改以參數設定的 DLX,就必須刪除佇列再重新宣告,也就是得先把佇列清空,並協調所有會宣告它的用戶端。政策可以在執行期間變更、套用到所有相符的佇列、會包含在 definitions 匯出中,而且集中在維運人員看得到的同一個地方。兩者同時存在時,以參數為準,這是避免使用參數的第二個理由:應用程式一旦設定了 x-dead-letter-exchange,就會把值鎖死,維運端不重新部署就無法覆寫。例外是 x-queue-type,它必須以參數設定,但這沒有問題,因為佇列類型永遠不會改變。
有一個陷阱:一個佇列只會套用一條政策,也就是優先順序最高的那條相符政策。如果您為死信處理定義一條政策,又為相同佇列的 max-length 或 delivery-limit 另外定義一條,只有其中一條會生效。請把佇列需要的所有鍵放進同一條政策定義中。
訊息代理將訊息送入死信時,會在 x-death 標頭中附加資料,這是一個陣列,每一組「佇列+原因」對應一筆項目。如果同一個佇列又因相同原因把同一則訊息送入死信,該項目的 count 會遞增,並移到陣列最前面。每筆項目都會記錄佇列、原因、訊息所帶的 exchange 與 routing key、時間戳記,以及涉及 TTL 時的 original-expiration。訊息代理也會一次性設定 x-first-death-reason、x-first-death-queue 與 x-first-death-exchange,並持續更新對應的 x-last-death-*。以下是重試迴圈跑完三圈後的標頭示意:
x-death:
- queue: orders.work
reason: rejected
exchange: orders
routing-keys: [order.created]
count: 3
time: 1788430492
- queue: orders.wait.30s
reason: expired
exchange: orders.retry
routing-keys: [order.created]
count: 3
time: 1788430462
original-expiration: "30000"
x-first-death-reason: rejected
x-first-death-queue: orders.work
x-first-death-exchange: orders
x-last-death-reason: rejected
x-last-death-queue: orders.work
x-last-death-exchange: orders死信處理可能形成循環,而訊息代理對此只有一條規則:如果訊息兩度抵達同一個佇列,且循環中沒有任何一段是拒絕,訊息就會被丟棄。只要有任何一段是消費者的拒絕,循環就會繼續。因此由 requeue=false 驅動的重試迴圈可以運作,因為每一圈都包含一次拒絕;反之,純粹以 TTL 構成的迴圈,例如設定了 message-ttl、並把訊息送入死信回到工作佇列的停放佇列,會在第二圈時默默丟棄訊息。
仲裁佇列改變了規則
仲裁佇列會以 x-delivery-count 標頭計算重新投遞次數,並由 delivery-limit 政策鍵(或 x-delivery-limit 參數)設定上限。超過上限後,若已設定 DLX,佇列會把訊息送入死信,否則直接丟棄。自 RabbitMQ 4.0 起,預設投遞上限為 20;在此之前則沒有上限。
這個預設值正是從傳統佇列遷移過來的團隊最常措手不及的地方。消費者捕捉到例外後以 requeue=true 呼叫 basic.nack,在傳統佇列上會無止境地空轉,浪費 CPU,但不會遺失任何東西。在沒有 DLX 的 4.x 仲裁佇列上,同樣的程式碼會在 20 次嘗試後丟棄訊息,唯一的痕跡只有一個計數器。請把 delivery-limit 設成您自己選定的值,並一律搭配 DLX。
仲裁佇列也透過 dead-letter-strategy 政策鍵支援兩種死信策略。預設的 at-most-once 會在不經確認的情況下重新發布。如果 DLX 不存在,或目標佇列無法使用或拒收訊息,訊息就沒了。這也是傳統佇列一直以來的保證等級。
at-least-once 會把送入死信的訊息保留在來源佇列中,直到 DLX 上綁定的每個佇列都確認收到為止。它要求來源必須是仲裁佇列、overflow 設為 reject-publish,並且設有 DLX。在內部,佇列的 leader 會執行一個死信 worker,官方文件稱之為死信消費者(dead-letter consumer):它從來源佇列讀取送入死信的訊息,以發布確認的方式發布到 DLX,並重試所有尚未確認的訊息。這會帶來三個結果。如果 DLX 不存在或目標停擺,訊息會依設計累積在來源佇列中,並計入它的長度與磁碟用量。由於投遞是至少一次,DLQ 可能收到重複的訊息。而內部的死信消費者只是管線,不是您的應用程式;死信佇列上仍然需要一個真正的消費者。
| 行為 | 傳統佇列 | 仲裁佇列 |
|---|---|---|
| 重新投遞上限 | 無,重新排入佇列的迴圈會永遠持續 | delivery-limit,4.x 預設為 20,之後送往 DLX 或丟棄 |
| 重新投遞計數 | 只有 redelivered 旗標 | x-delivery-count 標頭 |
| 死信策略 | 僅 at-most-once | at-most-once 或 at-least-once |
| 複寫 | 鏡像功能已於 4.0 移除 | 以 Raft 複寫為設計基礎 |
| 預設溢位行為 | drop-head | drop-head;at-least-once 需要 reject-publish |
不會遺失訊息的重試模式
基本的重試迴圈會使用一個等待佇列。工作佇列的 DLX 是一個重試用 exchange,它把訊息路由到一個設有佇列層級 message-ttl、且沒有任何消費者的等待佇列。等待佇列的 DLX 則是工作 exchange,且不設定 dead-letter-routing-key,讓訊息以原本的 routing key 重新進入。遇到暫時性故障的消費者以 requeue=false 拒絕訊息;訊息等 TTL 到期後就會回來。消費者從工作佇列、原因為 rejected 的 x-death 項目讀取嘗試次數,達到上限時就把訊息移到停放佇列,而不是再次拒絕。
若要實作指數退避,請為每個延遲層級各設一個等待佇列:wait.10s、wait.1m、wait.10m。不要在單一佇列中以個別訊息的 TTL 來做。無論傳統佇列或仲裁佇列,逾期的訊息都只會從佇列前端移除,因此排在前端、要等十分鐘的訊息,會擋住後面只需等十秒的訊息。採用分層佇列時,消費者依嘗試次數選擇層級,以該層級的 routing key 發布到重試 exchange,等待 publisher confirm,之後才確認原始訊息。在收到確認之前就 ack,正是由消費者驅動的重試會遺失訊息的地方。即便如此,工作佇列上仍應保留 DLX,作為 delivery-limit 的安全網。
另一種做法是 delayed message exchange 外掛:發布時帶上 x-delay 標頭,exchange 就會保留訊息直到延遲時間結束。代價在於持久性。延遲中的訊息存放在承載該 exchange 的節點本機儲存中,不會被複寫,所以一旦失去該節點,所有待處理的訊息都會跟著遺失;而大量待處理訊息累積時,外掛的效能也會下降。此外也沒有佇列可供檢查。若只是少量的短延遲,它很方便;但面對可能得在凌晨 3 點檢查的重試積壓,等待佇列雖然平淡無奇,卻清楚可見,而且宣告為仲裁佇列時還有複寫保護。
重試只對暫時性故障有幫助。因 payload 格式錯誤或參照了不存在的紀錄而必定失敗的訊息,應該直接送到停放佇列,因此請在消費者中區分可重試與不可重試的例外。而本頁介紹的每一種機制,都可能把同一則訊息投遞兩次:重試、重播與至少一次的死信處理保證的是投遞,而不是唯一性。消費者必須具備冪等性,以 message id 或業務鍵作為依據,否則一次重試就可能把一次失敗變成一筆重複扣款。
實作範例:以等待佇列與停放佇列處理訂單
拓樸如下:
- Exchange
orders(topic),以order.*綁定仲裁佇列orders.work。 - Exchange
orders.retry(fanout),搭配仲裁佇列orders.wait.30s,TTL 為 30 秒,送入死信後回到orders。 - Exchange
orders.dlx(fanout),搭配仲裁佇列orders.parking,不設 TTL,不做任何自動化處理。
兩條政策就能涵蓋:
rabbitmqctl set_policy --vhost orders orders-work '^orders\.work$' \
'{"dead-letter-exchange":"orders.retry","dead-letter-strategy":"at-least-once","overflow":"reject-publish","delivery-limit":5}' \
--apply-to queues --priority 10
rabbitmqctl set_policy --vhost orders orders-wait '^orders\.wait\.' \
'{"message-ttl":30000,"dead-letter-exchange":"orders","dead-letter-strategy":"at-least-once","overflow":"reject-publish"}' \
--apply-to queues --priority 10消費者負責強制執行嘗試次數上限,並以明確的方式移至停放佇列:先以確認模式發布,再進行 ack:
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每個環節都針對特定風險提供保護。處理到一半當機時,訊息會被重新排入佇列;連續五次就會觸發 delivery-limit,訊息會進入等待佇列而不是被丟棄。暫時性故障會等待 30 秒後回來,最多嘗試三次。永久性故障則在第一次出現時就移至停放佇列。至少一次的死信處理代表即使 orders.wait.30s 短暫無法使用,重試這一跳也不會遺失訊息。
維運死信佇列
死信佇列只有在有人知道它何時被填滿時才有用。以下四個訊號就能涵蓋大部分情況。
深度:停放佇列與每個等待佇列的 rabbitmq_queue_messages,可從啟用個別物件指標的 Prometheus 外掛,或 detailed 端點的 queue_coarse_metrics 指標系列取得。速率,它比深度更早反映變化:rabbitmq_global_messages_dead_lettered_*_total 計數器會依原因細分死信處理,若為至少一次,還會依確認狀態細分。消費者數量,它告訴您拓樸是否完整:停放佇列上的 rabbitmq_queue_consumers 應不為零,而每個等待佇列上則必須恰好為零,因為等待佇列上一旦有消費者,延遲就失去作用。存放時間,RabbitMQ 並未直接提供;請在取樣佇列時,從 x-parked-at 標頭或 x-death 中的 time 推估。
初始門檻建議如下,再依各服務調整:
- 平常完全沒有死信的佇列出現任何死信:立即發出警告,第一則永遠是調查成本最低的。
- 五分鐘內死信速率超過發布速率的百分之一:呼叫值班人員。
delivery_limit計數器只要有增加:進行調查,這代表消費者當機或重新排入佇列的迴圈,而不是業務層面的失敗。- 停放佇列深度超過依您的審查能力所訂的數量,或連續 30 分鐘持續上升:呼叫值班人員。
- 停放佇列連續十分鐘沒有消費者,或任何等待佇列上出現消費者:發出告警。
- 已設定
at-least-once,來源佇列深度上升而 DLQ 卻持平:代表 DLX 或其目標已經故障。
在移至停放佇列的當下,記錄訊息代理不會記錄的資訊:例外類別與訊息、消費者主機與建置版本、message id 與 correlation id、取自 x-death 的原始 exchange 與 routing key,以及嘗試次數。訊息代理知道訊息為何被送入死信;只有消費者知道到底哪裡出了錯。也請把原因附加為標頭,就像範例中的 x-parked-reason,讓之後打開佇列的人不必對照日誌就能看懂。除非訊息本體很小且不含敏感資料,否則不要記錄完整內容。本體本來就在佇列裡。
安全地重播訊息
重播是指把停放佇列中的訊息重新發布到工作 exchange。請先修正根本原因。把訊息重播給尚未修正的消費者,只會在停放佇列與工作佇列之間形成一個以人為中介的迴圈。
最簡單的工具,是以 rabbitmqctl set_parameter shovel 建立一個從停放佇列到工作 exchange 的動態 shovel。將 ack-mode 設為 on-confirm,讓訊息只有在工作佇列確認收到後才離開停放佇列;將 dest-exchange 設為工作 exchange,並且不設定 dest-exchange-key,以沿用原始 routing key;再把 src-delete-after 設為 queue-length,讓 shovel 只搬完啟動當下已存在的訊息,然後自行移除。管理介面的移動訊息(move messages)功能,底層其實就是 shovel。shovel 會依序重播所有訊息,不做任何篩選,而 x-death 會持續累積,這正是您要的結果:再次失敗的訊息會帶著更長的歷程回到停放佇列。
需要挑選訊息時,請使用重播消費者:一個小工具,以適中的 prefetch 從停放佇列消費,依標頭、時間或 id 篩選,以發布確認的方式發布,並在每次確認後 ack。請限制它的速率,因為週末累積起來的停放佇列,可能在週一早上一口氣壓垮下游資料庫。如果您希望嘗試次數重新計算,它可以移除 x-death,但應改為記錄一個 x-replay-count 標頭。
不要用未啟用確認的臨時腳本重新發布,不要在尖峰時段重播,也不要重播根本原因尚未查明的批次。
保留期限與磁碟
停放佇列是持久狀態。在仲裁佇列上,每一則訊息都會寫入每個成員的 Raft 日誌與 segment 檔案,因此三個成員的佇列在訊息停放期間會保有三份副本。送入死信的訊息往往是較大的那些,而且常常一放就是好幾天。請做好磁碟規劃。
以 max-length-bytes 為停放佇列設定上限,並將 overflow 設為 reject-publish,而不是 drop-head。drop-head 會在佇列滿載時默默捨棄最舊的證據。reject-publish 則讓滿載的停放佇列無法被忽視:送入它的死信處理會失敗,至少一次模式的來源佇列會保留積壓,您的告警也會觸發。無法被忽視,才是正確的。
不要在停放佇列上設定 message-ttl。保留期限應交給封存用的消費者處理:它把超過審查期限的訊息移到物件儲存或資料庫資料表後再 ack,讓佇列維持收件匣的角色,而不是變成檔案庫。您要避免的故障是真實存在的:沒人清理的停放佇列會持續增長,直到節點越過可用磁碟告警門檻,而磁碟告警會阻擋該節點上的所有發布者,讓緩慢累積的失敗演變成整個叢集的服務中斷。
我們在正式環境中看到的反模式
沒有消費者、也沒有告警的 DLQ。訊息會一直累積,直到磁碟告警觸發,或幾個月後有人在處理不相關的事故時才發現這個佇列。如果佇列在增長而您不會察覺,那您只是多費幾道工序設定了一個漏洞。
把訊息送入死信到佇列原本就綁定的 exchange,而且沒有變更 routing key。訊息會回到同一個佇列。如果它是因逾期或長度上限被捨棄,循環偵測會把它丟棄;如果它是被拒絕的,就會以全速在消費者之間熱迴圈,吃滿 CPU 並塞爆日誌。
沒有上限的重試。沒有嘗試次數上限時,永遠不會成功的訊息會無止境地循環,每一圈都消耗消費者的處理能力;而在 at-least-once 搭配 reject-publish 的情況下,還可能回堵到來源佇列。
在 4.x 上以鏡像傳統佇列承接 DLX。傳統佇列的鏡像功能已在 RabbitMQ 4.0 中移除,ha-* 政策鍵也不再生效。在 3.x 上有複寫保護的死信佇列,升級後會變成單一節點的傳統佇列,一旦該節點故障,證據也會跟著消失。請在升級之前把死信佇列轉換為仲裁佇列。
在 DLQ 本身設定 TTL。為了「保持整潔」而在停放佇列上設定一週的 message-ttl,刪掉的恰恰是調查所需的訊息;而如果停放佇列還會把訊息送入死信、回到工作佇列,這個 TTL 就會構成一個純逾期的循環,被循環偵測默默丟棄。
還有兩個較小的問題:記錄訊息本體後就直接 ack、而不是移至停放佇列,等於把一行日誌當成佇列;以及把停放佇列的消費者與工作消費者放在同一個程序中執行,導致填滿停放佇列的那個故障,同時也拖垮了原本負責清理它的程式。
延伸閱讀
死信處理建立在路由之上,DLX 的設計是否合理,取決於它周圍的 exchange 設計。我們的微服務的 exchange、佇列與 binding 指南專門討論這個主題。如果您還沒決定佇列類型,傳統佇列與仲裁佇列的比較說明了如何抉擇;本文的內容都假設凡是重要的工作負載都使用仲裁佇列。至於一開始就會讓停放佇列被填滿的各種常見故障模式,請參閱 RabbitMQ 十大疑難排解問題。
如果您的死信佇列正在被填滿而您不確定原因,或者您正在規劃 4.x 升級,希望在鏡像佇列不再可用之前先審查 DLX 拓樸,這正是我們的專長。AceMQ 是 Broadcom 指定的唯一 RabbitMQ MSP 合作夥伴,支援 RabbitMQ 3.8.x 到 4.x,並以依方案而定、最快 15 分鐘起的回應目標回應 P1 事故。請參閱我們的 RabbitMQ 技術支援方案,或進一步了解我們如何協助您運作 RabbitMQ。
常見問題
死信交換器和死信佇列有什麼不同?
死信交換器是佇列將訊息送入死信時,重新發布訊息的目的地 exchange。它就是一般的 exchange,沒有特殊類型。死信佇列則是任何綁定到該 exchange 的佇列,這個名稱只是慣例,並不是訊息代理裡的概念。RabbitMQ 只認得 exchange;訊息最後落在哪裡,取決於您宣告的 binding。這樣的分工很實用:一個 DLX 可以同時扇出到供重播用的停放佇列(parking lot)與供分析用的稽核佇列,也可以依原始 routing key 把各團隊的失敗訊息分送到各自的佇列。
RabbitMQ 會把無法路由的訊息送入死信嗎?
不會。死信處理只適用於已經進入佇列、且遭到拒絕、逾期、因長度上限被捨棄,或超過仲裁佇列投遞上限的訊息。發布到沒有相符 binding 的 exchange 的訊息,會在發布當下直接被丟棄;除非發布者設定了 mandatory 旗標,此時訊息會退回給發布者,或該 exchange 設定了 alternate exchange,此時訊息會被路由到那裡。如果無法路由的訊息對您很重要,請設定一個附帶專屬佇列的 alternate exchange,並以監控死信佇列的相同方式監控它。
在 RabbitMQ 中要如何計算重試次數?
讀取 x-death 標頭。每一筆項目代表一組「佇列+原因」,每當該佇列因該原因把訊息送入死信,其 count 欄位就會遞增。若是等待佇列式的重試迴圈,請找出 queue 為您的工作佇列、且 reason 為 rejected 的項目;它的 count 就是目前為止的嘗試次數。在仲裁佇列上,另有獨立的 x-delivery-count 標頭計算同一佇列內的重新投遞次數,它反映的是當機與重新排入佇列,而不是明確的拒絕。請在消費者端強制執行次數上限,達到上限時,以明確且經確認的發布將訊息移至停放佇列。
仲裁佇列可以搭配死信交換器使用嗎?
可以,而且仲裁佇列還多了兩項傳統佇列從未具備的功能。delivery-limit 政策會限制重新投遞次數,超過時就將訊息送入死信;自 RabbitMQ 4.0 起預設值為 20,因此務必設定 DLX,否則這些訊息會被直接丟棄。dead-letter-strategy 政策鍵可設為 at-least-once,讓送入死信的訊息保留在來源佇列中,直到目標佇列確認收到為止。這需要將 overflow 設為 reject-publish。來源佇列,以及理想上死信佇列本身,都應該使用仲裁佇列,讓故障證據也能被複寫。
如果死信交換器不存在,會發生什麼事?
宣告佇列或套用政策時,訊息代理並不會驗證 exchange 名稱,所以這項設定會被默默接受。在預設的 at-most-once 策略下,每一則送入死信的訊息都會被丟棄,沒有錯誤,也沒有任何日誌,這是 RabbitMQ 中最不易察覺的資料遺失方式之一。若在仲裁佇列上使用 at-least-once,送入死信的訊息會保留在來源佇列中,直到該 exchange 出現且目標佇列確認收到為止,因此變成來源佇列持續增長。請在 definitions 中宣告 DLX 及其佇列,並在死信速率未伴隨 DLQ 增長時發出告警。
死信佇列應該設定 TTL 嗎?
不應該。在停放佇列上設定 message-ttl,等於刪除您刻意保留下來、好讓人檢查與重播的訊息,而且刪除的時機取決於計時器,與底層問題是否已修正毫無關係。如果停放佇列還會把訊息送入死信、回到工作佇列,逾期就會形成一個沒有任何拒絕的循環,訊息代理會默默將其丟棄。請以封存用的消費者管理保留期限:把舊訊息移到持久儲存後再確認(ack),以 max-length-bytes 與 reject-publish 為佇列設定上限,並針對深度與存放時間設定告警。
Talk to an engineer
Need a hand with RabbitMQ?
Senior engineers who run it in production. Get a quote or a free consultation, no sales pitch.


