AMQP Troubleshooting Decision Tree
AMQP Troubleshooting Decision Tree
animation
amqp
protocols
messaging
Try Change the symptom to Messages lost on broker restart, then press Play troubleshooting.
Observe After Play troubleshooting, watch Diagnosis and Typical Impact for the selected symptom.
Explain Explain why delivery_mode=2 and durable=True address separate queue and message durability checks.
Technical boundaries. The tool selects likely root causes and fixes from the listed symptoms and chapter misconceptions. Battery impact needs a device measurement.
NoteTry It: AMQP Troubleshooting Decision Tree
Select the symptom you are observing in your AMQP system. The tool walks you through the most likely root causes and fixes based on the misconceptions covered in this chapter.
{
const diagnostics = {
"Messages lost on broker restart": {
misconception: "Misconception 1: Durable Queues vs Persistent Messages",
color: "#E67E22",
checks: [
{ question: "Is queue declared with durable=True?", fix: "Add durable=True to queue_declare()", severity: "critical" },
{ question: "Is delivery_mode=2 set on messages?", fix: "Set properties=pika.BasicProperties(delivery_mode=2)", severity: "critical" },
{ question: "Is the exchange also durable?", fix: "Add durable=True to exchange_declare()", severity: "high" },
{ question: "Are publisher confirms enabled?", fix: "Call channel.confirm_delivery() before publishing", severity: "high" }
],
stat: "Check queue and message durability separately",
typical_loss: "Transient messages may not survive a restart"
},
"Messages not arriving at expected queue": {
misconception: "Misconception 2: Wildcard Pattern Confusion",
color: "#9B59B6",
checks: [
{ question: "Using * where # is needed?", fix: "Replace * with # for variable-depth hierarchies", severity: "critical" },
{ question: "Do word counts match between pattern and routing key?", fix: "Count dot-separated segments: * requires exact match", severity: "critical" },
{ question: "Is the exchange type correct (topic vs direct)?", fix: "Wildcards only work with topic exchanges", severity: "high" },
{ question: "Does the binding exist?", fix: "Verify with rabbitmqctl list_bindings", severity: "medium" }
],
stat: "Test positive and negative routing keys",
typical_loss: "Unmatched messages can be discarded"
},
"Messages processed but still lost": {
misconception: "Misconception 3: Auto-Acknowledge Trap",
color: "#E74C3C",
checks: [
{ question: "Is auto_ack=True in basic_consume?", fix: "Set auto_ack=False and send manual ACKs after processing", severity: "critical" },
{ question: "Is ACK sent before processing completes?", fix: "Move basic_ack() to after successful save_to_database()", severity: "critical" },
{ question: "Does exception handler send NACK?", fix: "Add basic_nack(requeue=True) in except block", severity: "high" },
{ question: "Is dead letter queue configured?", fix: "Set x-dead-letter-exchange on queue for rejected messages", severity: "medium" }
],
stat: "Auto-ack settles on delivery, before processing",
typical_loss: "Delivered but unfinished work can be lost"
},
"Duplicate messages being executed": {
misconception: "Misconception 5: Exactly-Once is Not Automatic",
color: "#3498DB",
checks: [
{ question: "Is message_id set on published messages?", fix: "Set properties.message_id = str(uuid4()) on every publish", severity: "critical" },
{ question: "Is deduplication check in consumer?", fix: "Check message_id in the same transaction as the business side effect", severity: "critical" },
{ question: "Is deduplication storage persistent?", fix: "Use durable storage coordinated with the side effect", severity: "high" },
{ question: "Is prefetch window sized correctly?", fix: "Lower prefetch_count to reduce duplicate window on crash", severity: "medium" }
],
stat: "Broker delivery alone does not deduplicate side effects",
typical_loss: "Duplicate commands causing data corruption"
},
"Battery draining too fast on IoT device": {
misconception: "Misconception 4: AMQP is Not Always Better",
color: "#16A085",
checks: [
{ question: "Is AMQP the right protocol for this device?", fix: "Compare full wire traffic; MQTT's fixed header can be 2 bytes, AMQP 0-9-1 adds 8 bytes per frame before content", severity: "critical" },
{ question: "How many RTTs does connection setup require?", fix: "Without TLS, MQTT needs about 2 round trips (TCP + CONNECT/CONNACK); AMQP 0-9-1 needs about 5 (TCP, Start, Tune, Open, channel.open). TLS adds 1–2 to both.", severity: "high" },
{ question: "What is the device memory footprint?", fix: "Measure both client libraries on the target device", severity: "high" },
{ question: "Are complex routing features actually needed?", fix: "If simple pub/sub suffices, MQTT is more efficient", severity: "medium" }
],
stat: "Wire overhead depends on payload, frames, and session use",
typical_loss: "Battery impact needs a device measurement"
}
};
const d = diagnostics[symptom];
const severityColors = { critical: "#E74C3C", high: "#E67E22", medium: "#F1C40F" };
const severityLabels = { critical: "CRITICAL", high: "HIGH", medium: "MEDIUM" };
return html`<div style="margin: 20px 0; padding: 20px; background: #f8f9fa; border-left: 4px solid ${d.color}; border-radius: 4px;">
<h4 style="margin-top: 0; color: #2C3E50;">Diagnosis: ${d.misconception}</h4>
<div style="display: grid; grid-template-columns: 1fr 1fr; gap: 12px; margin: 15px 0;">
<div style="background: white; padding: 12px; border-radius: 6px; border-left: 3px solid ${d.color};">
<div style="font-size: 11px; color: #7F8C8D; text-transform: uppercase;">Frequency</div>
<div style="font-size: 16px; font-weight: bold; color: ${d.color}; margin-top: 4px;">${d.stat}</div>
</div>
<div style="background: white; padding: 12px; border-radius: 6px; border-left: 3px solid #7F8C8D;">
<div style="font-size: 11px; color: #7F8C8D; text-transform: uppercase;">Typical Impact</div>
<div style="font-size: 16px; font-weight: bold; color: #2C3E50; margin-top: 4px;">${d.typical_loss}</div>
</div>
</div>
<div style="background: white; padding: 15px; border-radius: 8px; margin-top: 15px;">
<div style="font-size: 13px; font-weight: bold; color: #2C3E50; margin-bottom: 12px;">Diagnostic Checklist:</div>
${d.checks.map((c, i) => html`<div style="margin: 8px 0; padding: 10px; background: #f8f9fa; border-radius: 6px; border-left: 3px solid ${severityColors[c.severity]};">
<div style="display: flex; align-items: center; gap: 8px;">
<span style="font-size: 11px; font-weight: bold; color: white; background: ${severityColors[c.severity]}; padding: 2px 6px; border-radius: 3px;">${severityLabels[c.severity]}</span>
<span style="font-size: 13px; color: #2C3E50; font-weight: bold;">${c.question}</span>
</div>
<div style="font-size: 12px; color: #16A085; margin-top: 6px; padding-left: 4px;">
Fix: <code style="background: #e8f8f5; padding: 2px 6px; border-radius: 3px;">${c.fix}</code>
</div>
</div>`)}
</div>
</div>`;
}