DLQ


1. Important Points#

SQS DLQ 用来隔离 poison messages，让主队列继续处理其他消息。DLQ 不是普通 retry queue，也不是 archive；它需要告警、排查和受控 redrive。

DLQ trigger:
    source queue has RedrivePolicy
    message receive count exceeds maxReceiveCount
    SQS moves that message to DLQ

receive count:
    increments when message is received again after visibility timeout expires
    not deleting the message is what causes retry and eventually DLQ

2. Redrive Policy#

{
  "deadLetterTargetArn": "arn:aws:sqs:ap-east-1:123456789012:prod-platform-checkout-order-payment-capture-dlq",
  "maxReceiveCount": "5"
}
maxReceiveCount choice:
    3:
        fail fast
        good for invalid payload or non-retriable business rule

    5:
        balanced default
        good for normal worker + transient downstream issue

    8 or more:
        only when failure is usually transient and duplicate side effect is well controlled
source queue retention vs DLQ retention:
    DLQ retention should usually be longer
    standard queue message keeps original enqueue timestamp when moved to DLQ
    so if source retention is long and DLQ retention is shorter, evidence can expire too early

FIFO caution:
    DLQ breaks strict end-to-end ordering expectation across the original processing flow
    only use FIFO DLQ when the business accepts that failed message leaves the main ordered stream

3. Redrive Allow Policy#

RedriveAllowPolicy:
    controls which source queues are allowed to use this queue as DLQ
    useful when one account has many teams and many queues
{
  "redrivePermission": "byQueue",
  "sourceQueueArns": [
    "arn:aws:sqs:ap-east-1:123456789012:prod-platform-checkout-order-payment-capture"
  ]
}
recommended:
    allow only explicit source queues
    avoid shared DLQ across unrelated workflows
    one important business queue usually deserves its own DLQ

4. DLQ Runbook#

when DLQ visible messages > 0:
    alert immediately
    sample a few messages safely
    inspect ApproximateReceiveCount, SentTimestamp, trace id, schema_version
    classify failure:
        invalid payload
        consumer bug
        permission error
        downstream timeout
        business invariant failure

    fix root cause first
    redrive small batch first
    watch source queue age, consumer error rate, and duplicate side effects
do not redrive immediately when:
    bad deploy is still live
    downstream dependency is still unhealthy
    duplicate side effect can charge user / send duplicate email / mutate state twice
Python SDK Forward