Message broker reliability sequence
Guaranteeing message delivery with acknowledgments, retries, and dead-letter queues.
Message-driven systems are powerful, but guaranteeing reliable delivery is subtle. This template shows the full sequence: how a publisher sends a message to a broker, how the broker delivers it to a consumer, how the consumer acknowledges success (or how retries kick in on failure), and where messages go if they exhaust all retries — the dead-letter queue, your safety net for debugging and manual recovery.
When to use this template
- Event-driven architecture docs — show engineers and architects how your async messaging handles failures and prevents message loss.
- Design reviews — when adding a new event-driven feature or rearchitecting an async path, walk through this diagram to ensure you're handling acknowledgments, retries, and dead letters.
- Incident postmortems — when a message delivery failure occurs, use this to trace where the contract broke and what the recovery process should be.
How to adapt it
Customize the retry strategy and dead-letter handling to your system:
- Adjust retry attempts and delays — change "attempt 1, attempt 2" to match your policy (some systems do 3–5 retries with exponential backoff; others do 1 retry).
- Add a poison-pill handler — if a message is malformed (not a transient failure), move it to a separate queue instead of retrying, so it doesn't clog the retry loop.
- Include monitoring — add a Monitoring system participant that checks the dead-letter queue and sends alerts when messages land there.
Visual edits regenerate clean Mermaid code, so you can paste it into your architecture docs or design-review notes.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
sequenceDiagram
participant Publisher
participant Broker
participant Consumer
participant DLQ as Dead Letter Queue
Publisher->>Broker: Publish message
Broker->>Consumer: Deliver message
alt Successful processing
Consumer->>Broker: Acknowledge
Broker->>Broker: Remove from queue
else Processing fails
Consumer-->>Broker: No ack (timeout)
Broker->>Consumer: Retry (attempt 1)
Consumer-->>Broker: No ack
Broker->>Consumer: Retry (attempt 2)
Consumer-->>Broker: No ack
Broker->>DLQ: Move to dead letter queue
DLQ->>Publisher: Alert: manual review needed
end
Frequently asked questions
- What does a message broker reliability sequence show?
- It diagrams the full lifecycle of a message from publisher to consumer: how the broker delivers the message, how the consumer acknowledges successful processing, what happens if processing fails (retries), and where messages go if they exhaust all retries (dead-letter queue). It makes the invisible reliability contract visible.
- Why is acknowledgment important in message-driven systems?
- Acknowledgment is the consumer's promise to the broker: 'I processed this message successfully.' If the consumer crashes before acknowledging, the broker will re-deliver the message to another consumer, preventing data loss. Without acks, messages can disappear silently.
- How do I adapt this for our message system?
- Rename 'Broker' to your actual broker (RabbitMQ, Kafka, AWS SQS); adjust the retry count and delay; add additional participants if you have a poison-pill handler or a notifications service that alerts on dead letters. The core flow — publish, deliver, ack-or-retry, dead-letter — stays the same.
- What should go in the dead-letter queue?
- Messages that failed to process after all retries. A separate process monitors the dead-letter queue, logs the failure (with the message and error), and alerts the team. Some teams implement manual review; others auto-archive after N days. It's your safety net for debugging production issues.
Related templates
Async job queue pattern
Producer queues work, consumer processes it, with retry and dead-letter paths.
Message queue retry logic
Publish-subscribe with exponential backoff and dead-letter queues.
Event-driven notification system
Event publisher, queue, consumers, and retry/failure handling.