Problema: ce se întâmplă cu mesajele care eșuează

Sistemele de mesagerie asincrone precum SQS, SNS, Kafka și EventBridge folosesc modelul cel puțin o dată livrare: un mesaj este livrat cel puțin o dată, dar ar putea fi livrat de mai multe ori (duplicate în caz de reîncercare). Acest lucru creează două scenarii critice:

  1. Erori tranzitorii: Serviciul din aval este temporar indisponibil. Reîncercarea automată rezolvă problema. După câteva încercări mesajul este procesat corect.
  2. Erori permanente (pilula otravitoare): mesajul este malformat, conține date care încalcă invarianțele de afaceri sau codul consumatorului are o eroare. Reîncercarea nu ajută: mesajul va continua să eșueze la nesfârșit, consumând potențial resurse blocarea procesării mesajelor ulterioare.

DLQ rezolvă al doilea scenariu: după un număr configurabil de încercări eșuate (maxReceiveCount în SQS, MAX_RETRY_ATTEMPTS în Kafka), mesajul este mutat în coada de scrisori moarte unde poate fi analizat şi reprocesat într-o manieră controlată.

DLQ: Contractul de Reziliență

  • Zero pierdere de date: Niciun mesaj nu este eliminat în tăcere
  • Izolarea problemei: Pastilele otravitoare nu blochează mesajele bune
  • Vizibilitate: Mesajele din DLQ sunt inspectabile pentru depanare
  • Reprocesare controlată: După ce problema este corectată, mesajele sunt reprocesate

DLQ în Amazon SQS

În SQS, DLQ este pur și simplu o altă coadă SQS configurată ca destinație pentru mesaje care depasesc maxReceiveCount. Mecanismul se bazează pe timeout de vizibilitate: atunci când un consumator primește un mesaj, acesta devine „invizibil” pentru alți consumatori pe toată durata a timeout-ului de vizibilitate. Dacă nu este șters în acest interval de timp (consumatorul a eșuat sau s-a prăbușit), SQS îl face vizibil din nou pentru o altă încercare.

Contorul ApproximateReceiveCount este crescut cu fiecare recepție. Când ajunge maxReceiveCount, SQS mută mesajul în DLQ configurat. 

# 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]
}

Inspectați și reprocesați de către 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();
    }
}

DLQ în AWS Lambda: nivel de funcție vs nivel de coadă

În AWS Lambda, DLQ poate fi configurat la două niveluri diferite, cu o semantică distinctă:

  • Coada SQS DLQ: Configurat în coada SQS sursă. Mesajele sunt mutate în DLQ când SQS depășește maxReceiveCount. Se întâmplă asta Înainte că Lambda este invocată. Aceasta este configurația recomandată pentru Lambda + SQS.
  • Funcția Lambda DLQ: configurat pe Lambda în sine (numai pentru invocări asincrone, nu pentru maparea sursei de evenimente cu SQS). Captați eșecurile invocării Lambda, nu coada. 
# 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 granular pentru lot

// 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}

DLQ în EventBridge

EventBridge are propriul nivel DLQ ţintă: dacă livrarea unui eveniment la țintă (Lambda, SQS) eșuează după toate încercările configurate, evenimentul este trimis în SQS DLQ specificat în dead_letter_config a regulii. 

# 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 ... }
# }

Model avansat: Reîncercați cu retragere progresivă folosind SQS Delay

SQS vă permite să configurați a întârziere pentru un singur mesaj (până la 15 minute). Combinat cu coada FIFO și grup de mesaje, este posibil să se implementeze un model de reîncercare exponențial fără a bloca alte mesaje: 

// 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(...);
        }
    }
}

Monitorizare DLQ: alerte esențiale

DLQ trebuie monitorizat activ. Un mesaj în DLQ indică o problemă reală care necesită atenție. Valorile SQS de monitorizat pe CloudWatch: 

# 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

Cele mai bune practici pentru DLQ în sisteme asincrone

  • DLQ obligatoriu pentru fiecare consumator: Nu există un sistem asincron în producție fără DLQ. Dacă lipsesc, mesajele eșuate se pierd sau blochează fluxul.
  • Monitorizați DLQ cu alerte de prag zero: orice mesaj din DLQ este un semn al unei probleme. Nu așteptați să se acumuleze sute înainte de a reacționa.
  • Îmbogățiți mesajele DLQ cu metadate: adăugați anteturi sau atribute cu tipul de eroare, stacktrace, numărul de reîncercări și marcajul de timp al eșecului. Fără aceste date, depanarea este aproape imposibilă.
  • Reținere îndelungată pe DLQ: configurați retenția de 14 zile (SQS maxim) sau cel puțin 30 de zile pe Kafka. Mesajele din DLQ trebuie să fie disponibile pentru analiză amânată.
  • Testați reprocesarea în mod regulat: DLQ este inutil dacă nu știi cum se reprocesează mesajele. Documentați și testați procesul de reprocesare.
  • Tipuri de erori separate: Luați în considerare DLQ-uri separate pentru erori permanente (sarcini utile corupte) și erori tranzitorii (servicii oprite). Strategia de reprocesare este diferită.

Anti-Pattern: ignorați DLQ

Cel mai periculos model este să configurați DLQ-ul și apoi să nu îl monitorizați. Mesajele se acumulează în tăcere săptămâni întregi, apoi cineva observă lipsesc datele critice. Configurați întotdeauna o alertă pe DLQ: este plasa de siguranță pe care nu trebuie să-l ignori niciodată.

Următorii pași din serie

  • Articolul 9 – Idempotenta la consumatori: reîncercări și reprocesare din DLQ poate cauza mesaje duplicate. Modelul cheie al idempotnței este principala apărare.
  • Articolul 10 – Model pentru căsuța de ieșire: asigurați-vă că un eveniment este publicat se întâmplă întotdeauna, chiar și în cazul unui accident de producător, folosind un tabel de expediere în baza de date.

Legătură cu alte serii

  • SQS vs SNS vs EventBridge (articolul 7): Fiecare serviciu AWS are propriul său serviciu semantica DLQ și reîncercați. Acest articol acoperă diferențele de configurare dintre servicii.
  • Coada de scrisori moarte Kafka (articolul 10 din seria Kafka): modelul DLQ în Kafka cu grupul de consumatori, reîncercați subiectul și reprocesarea are aceleași fundamente conceptual, dar o implementare diferită de SQS.