liveBook · Manning

Poison pill

As explained in Grokking Software Architecture

A malformed or otherwise unprocessable message that repeatedly fails when a consumer attempts to process it.

A poison pill is a message that repeatedly fails when a consumer tries to process it. Unlike a temporary network glitch, a malformed message will keep failing if retried, potentially trapping the consumer in an endless crash-and-redelivery loop. section 7.4.4 section 10.1

Keep the failure from holding up the rest of the system:

  • Set a maximum number of delivery attempts. After that limit, move the message to a Dead Letter Queue (DLQ) for inspection and possible reprocessing. section 7.4.4
  • Do not treat every failure the same: retries with backoff can help temporary glitches, while permanent faults such as corrupted payloads should fail fast or go to a DLQ. section 10.1

A message that keeps respawning

A shipping message with an Order ID of -1 triggers a logic exception. The broker redelivers it, the consumer crashes again, and repeated attempts can fill logs and consume CPU. A delivery limit can eject it to a DLQ so other messages keep flowing. section 7.4.4

"RetryPolicy": {
  "MaxDeliveryCount": 5,        // Try 5 times
  "BackoffStrategy": "Exponential", // Wait longer each time (1s, 2s, 4s, 8s)
  "DeadLetteringOnExpiration": true // If 5 fails, move to DLQ
}

A sample retry policy shows a maximum delivery count, exponential backoff, and dead-lettering on expiration. section 7.4.4

How Grokking Software Architecture covers it

How deep it goes
Defines the failure, illustrates its operational consequences, and describes retry limits and DLQ routing.
Examples
Illustrates an invalid Order ID crashing a shipping consumer on repeated delivery.
What you can do after
Diagnose/debug with it by distinguishing permanent message faults from temporary failures and routing persistent failures to a DLQ.
How it connects
Connects poison pills to message brokers, retries, exponential backoff, and Dead Letter Queues.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Grokking Software Architecture. The section links point to the parts of the book it draws on.