Skip to content

失敗したキューメッセージに対処する ​

max_attempts 回失敗したメッセージは dead になります。Edge は dead のメッセージを 14 日間保持するので、失敗の理由を確かめ、コンシューマーを直し、キューに戻すことができます。黙って失われることはありません。dead になるたびに queue.message.dead_lettered イベントも発生します。

このページの操作はどれもライブサイトを変えません。

ここでのキューは acme-marketing の orders(que_01M4XB7Q2W8E5R3T6Y9U1I4O0P)です。キューでバックグラウンド処理する を参照してください。

1. 発生したら知らせてもらう ​

Webhook を queue.message.dead_lettered に登録します。このイベントにはメッセージ本文が含まれるので、* では選ばれません。名前で指定するか、queue.* を使ってください。Edge のイベントを Webhook に送る を参照してください。

2. 何が失敗したかを見る ​

Web アプリで Distributions を開き、acme-marketing を選んで Queues を見ます。dead のメッセージがあるキューには、その数が表示されます。

text
acme-marketing の orders キューの dead メッセージと、失敗した理由を見せて。
bash
edge queues peek que_01M4XB7Q2W8E5R3T6Y9U1I4O0P --status dead
bash
curl -s "https://api.edge.deca-dev.com/v1/queues/que_01M4XB7Q2W8E5R3T6Y9U1I4O0P/messages?status=dead" \
  -H "Authorization: Bearer $EDGE_TOKEN"

エージェントは edge_queue_peek を実行します。

json
{
  "status": "dead",
  "messages": [
    {
      "message_id": "msg_01M4XB9D3F6G8H1J4K7L0Z2X5C",
      "attempts": 5,
      "last_error": "guest_status: the function answered 500",
      "dead_at": "2026-10-19T03:40:12+00:00",
      …
    }
  ]
}

本文には個人データが含まれうるので、既定では含まれません。見るには --bodies(include_bodies=true)を付けます。誰が何件読んだかは Edge が記録します。last_error の元になったバッチの実行は edge queues runs に、関数自身の出力は source が queue のログにあります。

last_error が expired のメッセージは、キューの retention_days の間に一度も届けられなかったものです。コンシューマーで失敗したわけではありません。

3. 戻すか、削除する ​

コンシューマーを直したら、redrive で dead のメッセージを試行回数をリセットしてキューに戻します。purge は完全に削除します。Web アプリでは、キューの行に Redrive dead と Purge dead があります。purge は 2 回クリックして確定します。

text
acme-marketing の orders キューの dead メッセージを redrive して。
bash
edge queues redrive que_01M4XB7Q2W8E5R3T6Y9U1I4O0P
# 一部だけ:
edge queues redrive que_01M4XB7Q2W8E5R3T6Y9U1I4O0P --message msg_01M4XB9D3F6G8H1J4K7L0Z2X5C
# 削除する:
edge queues purge que_01M4XB7Q2W8E5R3T6Y9U1I4O0P --status dead
bash
curl -s -X POST https://api.edge.deca-dev.com/v1/queues/que_01M4XB7Q2W8E5R3T6Y9U1I4O0P/redrive \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
curl -s -X POST https://api.edge.deca-dev.com/v1/queues/que_01M4XB7Q2W8E5R3T6Y9U1I4O0P/purge \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "dead", "confirm": true}'

エージェントは edge_queue_redrive({"redriven": 3})か edge_queue_purge({"deleted": 3})を実行します。purge は元に戻せません。また、指定した状態のメッセージだけが対象です。dead を purge しても待っているメッセージは残ります。処理中のバッチにあるメッセージが purge されることはありません。

次に ​

コンシューマーを直す間、新しいバッチを止めたいときはキューを一時停止します(Web アプリの Pause、または edge queues update que_01M4XB7Q2W8E5R3T6Y9U1I4O0P --paused true)。メッセージは届き続け、再開を待ちます。メッセージの種類ごとの保持期間は 上限 にあります。