iii-dead-letter-queues

デッドレターキュー

類似：SQS DLQ、RabbitMQ デッドレターエクスチェンジ

主要な概念

以下の概念は、タスクに該当する場合に使用してください。キューの障害すべてに、手動で DLQ に介入する必要があるわけではありません。

• ジョブは指数バックオフ（backoff_ms * 2^attempt）を伴う max_retries を使い切ると、DLQ に移動します
• 各 DLQ エントリーには、元のペイロード、最後に発生したエラー、タイムスタンプ、ジョブのメタデータが保持されます
• 組み込みの iii::queue::redrive 関数または iii trigger CLI コマンドを使って再投入します
• 再投入すると試行回数カウンターがゼロにリセットされ、ジョブは新たなリトライサイクルに入ります
• 再投入する前に必ず調査して修正をデプロイしてください。むやみに再投入すると障害が繰り返されます
• DLQ は Builtin アダプターと RabbitMQ アダプターで利用できます

アーキテクチャ

キューコンシューマーでジョブの処理に失敗します。エンジンは max_retries に達するまで、指数バックオフを使って再試行します。上限に達すると、メッセージは DLQ に移動します。オペレーターが障害を調査して修正をデプロイした後、DLQ を再投入して失敗したすべてのジョブを再実行します。

使用する iii プリミティブ

プリミティブ	用途
trigger({ function_id: 'iii::queue::redrive', payload: { queue } })	名前を指定したキューの DLQ ジョブをすべて再投入します
trigger({ function_id: 'iii::queue::status', payload: { queue } })	キューと DLQ のステータスを確認します
iii trigger --function-id='iii::queue::redrive' --payload='{"queue":"name"}'	CLI 再投入コマンド（エンジンバイナリに含まれます）
--timeout-ms	トリガーのタイムアウトを設定する CLI フラグ（デフォルトは 30s）
iii-config.yaml の queue_configs	max_retries と backoff_ms を設定します

リファレンス実装

完全な動作例については、../references/dead-letter-queues.js を参照してください。DLQ ステータスの確認、

Python 版もあります：../references/dead-letter-queues.py

Rust 版もあります：../references/dead-letter-queues.rs SDK と CLI による失敗ジョブの再投入、およびリトライ動作の設定について説明しています。

一般的なパターン

このパターンを使用するコードには、該当する場合、一般に以下が含まれます。

• await iii.trigger({ function_id: 'iii::queue::redrive', payload: { queue: 'payment' } }) — SDK による再投入
• iii trigger --function-id='iii::queue::redrive' --payload='{"queue": "payment"}' — CLI による再投入
• iii trigger --function-id='iii::queue::redrive' --payload='{"queue": "payment"}' --timeout-ms=60000 — カスタムタイムアウトを指定した再投入
• 再投入すると { queue: 'payment', redriven: 12 } が返され、再実行されたジョブ数が示されます
• RabbitMQ UI（http://localhost:15672）で確認し、iii.__fn_queue::{name}::dlq.queue を探します
• ベストプラクティス：障害を調査し、修正をデプロイしてから再投入します
• DLQ の深さを運用アラートの指標として監視します

このパターンの応用

タスクに当てはまる場合は、以下の応用方法を使用してください。

• 障害への許容度に応じて、queue_configs の max_retries と backoff_ms を設定します
• 運用管理のために iii::queue::redrive を呼び出す管理用エンドポイントを構築します
• iii::queue::status を使用して、再投入の前後に DLQ の深さを確認します
• 開発・テスト環境では、失敗をより早く顕在化させるためにリトライ回数を減らします
• RabbitMQ を本番環境で使用する場合は、管理 UI でメッセージを詳しく確認します
• DLQ の深さがしきい値に達したときにトリガーされるアラート関数の構築を検討します

エンジンの設定

キューごとの max_retries と backoff_ms は、iii-config.yaml の queue_configs で設定します。注釈付きの設定リファレンス全体については、../references/iii-config.yaml を参照してください。

パターンの境界

• キュー処理のパターン（enqueue、concurrency、FIFO）には、iii-queue-processing を優先してください。
• キューの設定（retries、backoff、adapters）には、iii-engine-config を優先してください。
• 関数の登録とトリガーには、iii-functions-and-triggers を優先してください。
• 主な問題が失敗したジョブの調査または再処理である場合は、iii-dead-letter-queues を使用してください。

使用する場面

• タスクの主な対象が iii engine の iii-dead-letter-queues である場合に、このスキルを使用してください。
• リクエストでこのパターン、または同等の実装が直接求められた場合に適用してください。

境界

• 無関係なタスクに対する汎用的な代替手段として、このスキルを使用しないでください。
• より具体的な iii スキルが適している場合は、このスキルを適用してはいけません。
• このスキルの例を適用する前に、環境と安全性の制約を必ず確認してください。