問題: 失敗したメッセージはどうなるか

SQS、SNS、Kafka、EventBridge などの非同期メッセージング システムでは、このパターンが使用されます。 少なくとも 1 回の配信: メッセージは少なくとも 1 回配信されます。 ただし、複数回配信される可能性があります (再試行の場合は重複します)。 これにより、次の 2 つの重要なシナリオが作成されます。

  1. 一時的なエラー：ダウンストリームサービスは一時的に利用できません。 自動再試行により問題は解決されます。数回試行すると、メッセージは正しく処理されます。
  2. 永続的なエラー (毒薬): メッセージは不正な形式であり、データが含まれています ビジネスの不変条件に違反しているか、消費者のコードにバグがあります。再試行しても役に立ちません: メッセージは無期限に失敗し続け、リソースを消費する可能性があります 後続のメッセージの処理をブロックします。

DLQ は 2 番目のシナリオ、つまり設定可能な回数試行が失敗した後 (maxReceiveCount SQSでは、 MAX_RETRY_ATTEMPTS Kafka では)、メッセージはデッドレターキューに移動されます。 制御された方法で分析および再処理できます。

DLQ: レジリエンス契約

  • データ損失ゼロ: メッセージは黙って破棄されません
  • 問題の切り分け: 毒薬は良いメッセージをブロックしない
  • 可視性: DLQ 内のメッセージはデバッグのために検査可能です
  • 管理された再処理: 問題が修正された後、メッセージは再処理されます。

Amazon SQS の DLQ

SQS では、DLQ はメッセージの宛先として構成された別の SQS キューです。 を超えるもの maxReceiveCount。メカニズムは以下に基づいています 可視性タイムアウト: コンシューマがメッセージを受信すると、その期間の間、他のコンシューマにはメッセージが「見えなくなります」 可視性タイムアウトの。その期間内に削除されなかった場合 (コンシューマーが失敗またはクラッシュした場合)、 SQS により、もう一度試行できるように再度表示されるようになります。

カウンター ApproximateReceiveCount 受信するたびに増加します。 届いたら maxReceiveCount, SQS は、構成された DLQ にメッセージを移動します。 

# Configurazione DLQ per SQS con Terraform

# 1. Crea la DLQ (stessa tipologia della coda principale)
resource "aws_sqs_queue" "ordini_dlq" {
  name                       = "ordini-queue-dlq"
  message_retention_seconds  = 1209600  # 14 giorni (massimo SQS)
  visibility_timeout_seconds = 300      # 5 minuti per elaborare dalla DLQ

  # CloudWatch alarm sulla DLQ
  tags = {
    Environment = "production"
    Alert       = "critical"
  }
}

# 2. Crea la coda principale con redrive policy che punta alla DLQ
resource "aws_sqs_queue" "ordini" {
  name                       = "ordini-queue"
  visibility_timeout_seconds = 60       # 60s per elaborare ogni messaggio
  receive_wait_time_seconds  = 20       # long polling
  message_retention_seconds  = 345600   # 4 giorni

  redrive_policy = jsonencode({
    deadLetterTargetArn = aws_sqs_queue.ordini_dlq.arn
    maxReceiveCount     = 3  # 3 tentativi falliti -> DLQ
  })
}

# 3. CloudWatch Alarm: alert quando la DLQ ha messaggi
resource "aws_cloudwatch_metric_alarm" "dlq_not_empty" {
  alarm_name          = "ordini-dlq-not-empty"
  comparison_operator = "GreaterThanThreshold"
  evaluation_periods  = "1"
  metric_name         = "ApproximateNumberOfMessagesVisible"
  namespace           = "AWS/SQS"
  period              = "60"
  statistic           = "Sum"
  threshold           = "0"
  alarm_description   = "CRITICO: messaggi in DLQ ordini"

  dimensions = {
    QueueName = aws_sqs_queue.ordini_dlq.name
  }

  alarm_actions = [aws_sns_topic.alerts.arn]
}

DLQ SQS による検査と再処理

// DlqReprocessor.java - Riprocessa messaggi dalla DLQ SQS
import software.amazon.awssdk.services.sqs.*;
import software.amazon.awssdk.services.sqs.model.*;

public class SqsDlqReprocessor {

    private final SqsClient sqsClient;
    private final String dlqUrl;
    private final String mainQueueUrl;

    // Riprocessa tutti i messaggi dalla DLQ verso la coda principale
    public void reprocessAll() {
        int reprocessed = 0;
        List<Message> messages;

        do {
            messages = receiveMessages(dlqUrl, 10);

            for (Message message : messages) {
                try {
                    // Analizza il messaggio per capire il tipo di errore
                    System.out.printf("Riprocesso messaggio: id=%s, receiveCount=%s%n",
                        message.messageId(),
                        message.attributes().get(MessageSystemAttributeName.APPROXIMATE_RECEIVE_COUNT)
                    );

                    // Rimanda alla coda principale (con delay opzionale)
                    sqsClient.sendMessage(
                        SendMessageRequest.builder()
                            .queueUrl(mainQueueUrl)
                            .messageBody(message.body())
                            .messageAttributes(message.messageAttributes())
                            .delaySeconds(0)
                            .build()
                    );

                    // Elimina dalla DLQ
                    sqsClient.deleteMessage(
                        DeleteMessageRequest.builder()
                            .queueUrl(dlqUrl)
                            .receiptHandle(message.receiptHandle())
                            .build()
                    );

                    reprocessed++;

                } catch (Exception e) {
                    System.err.println("Errore reprocessing: " + e.getMessage());
                    // Non eliminare: rimane in DLQ
                }
            }

        } while (!messages.isEmpty());

        System.out.printf("Reprocessing completato: %d messaggi rimandati%n", reprocessed);
    }

    private List<Message> receiveMessages(String queueUrl, int maxMessages) {
        return sqsClient.receiveMessage(
            ReceiveMessageRequest.builder()
                .queueUrl(queueUrl)
                .maxNumberOfMessages(maxMessages)
                .waitTimeSeconds(5)
                .attributeNames(QueueAttributeName.ALL)
                .build()
        ).messages();
    }
}

AWS Lambda の DLQ: 関数レベルとキューレベル

AWS Lambda では、DLQ は、異なるセマンティクスを持つ 2 つの異なるレベルで設定できます。

  • SQSキューDLQ: ソース SQS キューで構成されます。メッセージが移動されました SQS が maxReceiveCount。これが起こる 前に Lambda が呼び出されるということです。これは、Lambda + SQS の推奨構成です。
  • ラムダ関数 DLQ: Lambda 自体で構成されます (非同期呼び出しの場合のみ、 SQS を使用したイベント ソース マッピングではありません)。キューではなく、Lambda 呼び出しの失敗をキャッチします。 
# Terraform: Lambda con SQS event source e DLQ configurata sulla coda

resource "aws_lambda_function" "ordini_consumer" {
  function_name = "ordini-consumer"
  handler       = "handler.lambda_handler"
  runtime       = "python3.12"
  role          = aws_iam_role.lambda_role.arn
  timeout       = 30  # 30 secondi per messaggio

  # DLQ a livello di Lambda (solo per invocazioni async dirette)
  dead_letter_config {
    target_arn = aws_sqs_queue.lambda_dlq.arn
  }
}

# SQS come event source per Lambda
resource "aws_lambda_event_source_mapping" "sqs_trigger" {
  event_source_arn = aws_sqs_queue.ordini.arn
  function_name    = aws_lambda_function.ordini_consumer.arn
  batch_size       = 10
  enabled          = true

  # Bisection: in caso di errore batch, prova prima con metà messaggi
  # Aiuta a isolare il poison pill senza mandare tutti in DLQ
  bisect_batch_on_function_error = true

  # Report batch item failures: Lambda può indicare quali specifici
  # messaggi nel batch hanno fallito (solo quelli vanno in DLQ)
  function_response_types = ["ReportBatchItemFailures"]
}

ReportBatchItemFailures: バッチの詳細な DLQ

// Handler Lambda Python con batch item failures
// Solo i messaggi falliti vanno in DLQ, non l'intero batch

def lambda_handler(event, context):
    """
    ReportBatchItemFailures: ritorna solo i message ID falliti.
    SQS mandrà in DLQ solo quelli, non il batch intero.
    """
    failed_items = []

    for record in event['Records']:
        message_id = record['messageId']
        try:
            # Elabora il messaggio
            payload = json.loads(record['body'])
            process_ordine(payload)
            print(f"Successo: {message_id}")

        except PermanentError as e:
            # Errore permanente: vai in DLQ subito
            print(f"PERMANENTE: {message_id} - {e}")
            failed_items.append({'itemIdentifier': message_id})

        except TransientError as e:
            # Errore transitorio: riprova (non aggiungere a failed)
            # SQS ritenterà l'intero batch se almeno uno fallisce
            # Con ReportBatchItemFailures, solo i falliti vengono ritentati
            print(f"TRANSITORIO: {message_id} - {e}")
            failed_items.append({'itemIdentifier': message_id})

    return {'batchItemFailures': failed_items}

EventBridge の DLQ

EventBridge には独自の DLQ レベルがあります ターゲット：イベント配信の場合 構成されたすべての再試行後にターゲット (Lambda、SQS) への接続が失敗すると、イベントが送信されます。 で指定された SQS DLQ 内 dead_letter_config ルールの。 

# EventBridge DLQ per target Lambda
resource "aws_cloudwatch_event_target" "ordini_lambda" {
  rule           = aws_cloudwatch_event_rule.ordini.name
  event_bus_name = aws_cloudwatch_event_bus.mioapp.name
  arn            = aws_lambda_function.ordini_consumer.arn

  # Retry policy di EventBridge: quanti tentativi prima di DLQ
  retry_policy {
    maximum_event_age_in_seconds = 86400  # Riprova per max 24h
    maximum_retry_attempts       = 185    # ~exponential backoff su 24h
  }

  # DLQ per eventi non consegnati
  dead_letter_config {
    arn = aws_sqs_queue.eventbridge_dlq.arn
  }
}

# L'evento in DLQ EventBridge include metadata di debug
# {
#   "version": "1.0",
#   "timestamp": "...",
#   "requestId": "...",
#   "condition": "...",
#   "approximateInvokeCount": 185,
#   "requestParameters": {
#     "FunctionName": "ordini-consumer"
#   },
#   "responseParameters": {
#     "statusCode": 500,
#     "errorCode": "Lambda.ServiceException"
#   },
#   "originalEvent": { ... l'evento originale ... }
# }

高度なパターン: SQS 遅延を使用したプログレッシブ バックオフでの再試行

SQS を使用すると、 単一メッセージの遅延 (最大15分)。 FIFO キューと組み合わせると、 メッセージグループ、実装することが可能です 他のメッセージをブロックしない指数関数的な再試行パターン: 

// RetryWithSqsDelay.java - Retry progressivo con SQS message delay
public class SqsExponentialRetry {

    private static final int MAX_ATTEMPTS = 5;
    private static final int MAX_DELAY_SECONDS = 900;  // 15 minuti (max SQS)

    public void handleWithRetry(String queueUrl, Message sqsMessage) {
        // Leggi il numero di tentativi corrente dal message attribute
        int currentAttempt = Integer.parseInt(
            sqsMessage.messageAttributes()
                .getOrDefault("retryAttempt",
                    MessageAttributeValue.builder().stringValue("0").build())
                .stringValue()
        );

        try {
            processMessage(sqsMessage.body());
            // Successo: elimina dalla coda
            sqsClient.deleteMessage(...);

        } catch (TransientException e) {
            if (currentAttempt >= MAX_ATTEMPTS) {
                // Troppi tentativi: manda in DLQ manuale
                sendToManualDLQ(sqsMessage, e);
                sqsClient.deleteMessage(...);
                return;
            }

            // Calcola delay esponenziale (1s, 2s, 4s, 8s, 16s...)
            int delaySeconds = (int) Math.min(
                Math.pow(2, currentAttempt),
                MAX_DELAY_SECONDS
            );

            // Rimanda il messaggio con delay e contatore incrementato
            sqsClient.sendMessage(
                SendMessageRequest.builder()
                    .queueUrl(queueUrl)
                    .messageBody(sqsMessage.body())
                    .delaySeconds(delaySeconds)
                    .messageAttributes(Map.of(
                        "retryAttempt", MessageAttributeValue.builder()
                            .stringValue(String.valueOf(currentAttempt + 1))
                            .dataType("Number")
                            .build()
                    ))
                    .build()
            );

            // Elimina il messaggio originale (non usare la DLQ automatica)
            sqsClient.deleteMessage(...);
        }
    }
}

DLQ モニタリング: 重要なアラート

DLQ はアクティブに監視する必要があります。 DLQ のメッセージは実際の問題を示しています それは注意が必要です。 CloudWatch で監視する SQS メトリクス: 

# CloudWatch Metric Alarms per DLQ - AWS CLI

# Alert: qualsiasi messaggio in DLQ (soglia 0)
aws cloudwatch put-metric-alarm \
  --alarm-name "ordini-dlq-not-empty" \
  --alarm-description "CRITICO: messaggi in DLQ ordini" \
  --metric-name "ApproximateNumberOfMessagesVisible" \
  --namespace "AWS/SQS" \
  --dimensions Name=QueueName,Value=ordini-queue-dlq \
  --period 60 \
  --evaluation-periods 1 \
  --statistic Sum \
  --comparison-operator GreaterThanThreshold \
  --threshold 0 \
  --alarm-actions "arn:aws:sns:eu-west-1:123456:alerts-topic"

# Metriche importanti da monitorare su DLQ:
# - ApproximateNumberOfMessagesVisible: messaggi pronti per essere letti
# - ApproximateNumberOfMessagesNotVisible: messaggi in processing
# - NumberOfMessagesSent: rate di arrivo in DLQ (crescita = problema)
# - NumberOfMessagesDeleted: rate di reprocessing

非同期システムにおける DLQ のベスト プラクティス

  • DLQ はすべての消費者に必須: 本番環境には非同期システムはありません DLQなしで。欠落している場合、失敗したメッセージは失われるか、フローをブロックします。
  • ゼロしきい値アラートによる DLQ の監視: DLQ 内のメッセージはすべて 問題の兆候。何百ものデータが蓄積されるまで待ってから反応しないでください。
  • DLQ メッセージをメタデータで強化する: ヘッダーまたは属性を追加します エラーの種類、スタックトレース、再試行回数、失敗のタイムスタンプが含まれます。 このデータがなければデバッグはほぼ不可能です。
  • DLQ での長期保持: 14 日間の保存期間 (最大 SQS) を設定します。 または Kafka で少なくとも 30 日間。 DLQ 内のメッセージは遅延分析に使用できる必要があります。
  • 再処理を定期的にテストする：DLQは知らないとダメだよ メッセージを再処理する方法。再処理プロセスを文書化してテストします。
  • 個別のエラータイプ: 永続的なエラーについては別の DLQ を検討してください (ペイロードの破損) および一時的なエラー (サービスのダウン)。再処理戦略は異なります。

アンチパターン: DLQ を無視する

最も危険なパターンは、DLQ を設定して監視しないことです。 メッセージは数週間にわたって静かに蓄積され、その後誰かが気づきます 重要なデータが欠落しています。 DLQ には常にアラートを設定します。これはセーフティ ネットです。 決して無視してはいけないこと。

シリーズの次のステップ

  • 第 9 条 – 消費者の冪等性: DLQ からの再試行と再処理 メッセージが重複する可能性があります。冪等性キー パターンが主な防御です。
  • 第 10 条 – 送信ボックスのパターン: イベントが公開されていることを確認します データベース内の送信トレイ テーブルを使用すると、プロデューサーがクラッシュした場合でも常に発生します。

他シリーズとの連携

  • SQS vs SNS vs EventBridge（第7条）: 各 AWS サービスには独自のサービスがあります DLQ と再試行のセマンティクス。この記事では、サービス間の構成の違いについて説明します。
  • Kafka Dead Letter Queue (Kafka シリーズの記事 10): DLQ パターン Kafka ではコンシューマー グループを使用して、トピックを再試行し、再処理しますが、基盤は同じです 概念的ですが、SQS とは異なる実装です。