Rabbitmq

---
name: rabbitmq
description: "Expert coverage of RabbitMQ 4.x message broker across all supported versions (4.0-4.2): AMQP 0-9-1/1.0 protocols, exchange routing, quorum queues, streams, Khepri metadata store, clustering, and operational troubleshooting. Use for \"RabbitMQ\", \"AMQP\", \"exchange\", \"binding\", \"quorum queue\", \"classic queue\", \"RabbitMQ stream\", \"super stream\", \"dead letter exchange\", \"DLX\", \"publisher confirm\", \"consumer ack\", \"prefetch\", \"vhost\", \"Khepri\", \"rabbitmqctl\", \"rabbitmq-diagnostics\", \"fanout\", \"topic exchange\", \"headers exchange\", \"MQTT RabbitMQ\", \"STOMP\", \"RabbitMQ cluster\", \"network partition\", \"quorum queue replication\", \"rabbitmq-plugins\", \"management UI\"."
license: MIT
---

# RabbitMQ

This skill covers RabbitMQ across the 4.x release line (4.0 through 4.2), including:

- Exchange-binding-queue architecture (direct, fanout, topic, headers, alternate exchanges, E2E bindings)
- Queue types: quorum queues (Raft-based replication), classic queues (CQv2), streams (append-only log)
- Protocols: AMQP 0-9-1 (primary), AMQP 1.0 (native core since 4.0), MQTT 5.0, STOMP
- Khepri metadata store (Raft-based replacement for Mnesia, default in 4.2)
- Publisher confirms, consumer acknowledgments, prefetch/QoS
- Dead Letter Exchanges (DLX), message TTL, queue TTL, delivery limits
- Clustering, peer discovery, network partition handling strategies
- Virtual hosts, users, permissions, policies
- Management UI, HTTP API, Prometheus metrics, CLI tools
- Super streams (partitioned streams), Single Active Consumer
- TLS configuration, OAuth 2.0 authentication

Read this skill for RabbitMQ architecture, exchange/queue design, producer/consumer patterns, troubleshooting, and best practices that apply across 4.x versions.

## How to Approach Tasks

1. **Classify** the request:
   - **Troubleshooting** -- Load `references/diagnostics.md` for connection issues, memory/disk alarms, queue buildup, partition handling, and CLI tool usage
   - **Architecture / design** -- Load `references/architecture.md` for exchange types, queue types, streams, Khepri, clustering, protocols, and replication mechanics
   - **Best practices** -- Load `references/best-practices.md` for queue type selection, producer/consumer tuning, DLX patterns, security, monitoring, and migration guidance

2. **Identify version** -- Key version gates:
   - AMQP 1.0 native core, CQ mirroring removed, CQv1 removed (4.0)
   - Khepri stable, new K8s peer discovery, rabbitmqadmin v2 (4.1)
   - Khepri default for new deployments, SQL stream filters, fanout optimization (4.2)

3. **Load context** -- Read the relevant reference file before answering.

4. **Analyze** -- Consider queue type selection, exchange routing, replication factor, prefetch tuning, DLX configuration, and memory/disk implications.

5. **Recommend** -- Provide actionable guidance with `rabbitmqctl` commands, config snippets, and code examples.

6. **Verify** -- Suggest validation steps (rabbitmq-diagnostics, management UI, Prometheus metrics).

## Core Architecture

### How RabbitMQ Works

```
Publisher ──► Exchange ──► Binding ──► Queue/Stream ──► Consumer
                │                         │
         routing logic              acknowledgment
         (key, pattern,             (ack/nack/reject)
          headers)
```

**Exchanges** route messages to queues/streams via bindings. Exchange types: direct (exact key match), fanout (broadcast), topic (pattern match with `*` and `#`), headers (attribute match).

**Queues** store messages for consumers. Three types in 4.x:
- **Quorum queues:** Raft-replicated, durable, production default. Support delivery limits, at-least-once DLX, two-tier priority.
- **Classic queues:** Non-replicated (mirroring removed in 4.0). CQv2 storage only. Use for non-critical, scratch workloads.
- **Streams:** Append-only immutable logs. Multiple consumers read at different offsets. Retention by age/size. Support super streams (partitioned).

**Bindings** are routing rules: source exchange, destination (queue/stream/exchange), routing key, optional arguments.

### Protocols

| Protocol | Port | TLS Port | Status in 4.x |
|---|---|---|---|
| AMQP 0-9-1 | 5672 | 5671 | Primary protocol |
| AMQP 1.0 | 5672 | 5671 | Native core (shared port, protocol negotiation) |
| MQTT 5.0 | 1883 | 8883 | Plugin (`rabbitmq_mqtt`), native routing since 3.12 |
| STOMP | 61613 | -- | Plugin (`rabbitmq_stomp`) |
| Stream Protocol | 5552 | 5551 | Native stream client protocol |
| Management HTTP | 15672 | -- | Plugin (`rabbitmq_management`) |
| Prometheus | 15692 | -- | Plugin (`rabbitmq_prometheus`) |

### Khepri Metadata Store

Khepri is a Raft-based, tree-structured replicated database replacing Mnesia for metadata (exchanges, queues, bindings, users, vhosts, policies):
- Default for new deployments in 4.2 (`khepri_db` feature flag = Stable)
- Unified Raft consensus (same algorithm as quorum queues and streams)
- Eliminates Mnesia partition-related binding inconsistency bugs
- Migration from Mnesia is irreversible -- test before production

```bash
# Enable Khepri on a running cluster
rabbitmqctl enable_feature_flag khepri_db

# Verify metadata store
rabbitmq-diagnostics metadata_store_status
```

### Quorum Queue Essentials

```python
# Declare a quorum queue
channel.queue_declare(
    queue='orders.processing',
    durable=True,
    arguments={'x-queue-type': 'quorum'}
)
```

| Cluster Nodes | Default Replicas | Tolerated Failures |
|---|---|---|
| 3 | 3 | 1 |
| 5 | 5 | 2 |
| 7 | 3 (not all 7) | 1 |

Control initial size with `x-quorum-initial-group-size`. Default delivery limit: 20 redeliveries before dead-lettering.

### Publisher Confirms and Consumer Acks

**Publisher confirms:** Channel enters confirm mode; broker sends `basic.ack` after disk persistence (for persistent messages on durable queues).

**Consumer acknowledgments:** Manual `basic.ack` after processing (recommended). `basic.nack` with `requeue=False` sends to DLX. Set `prefetch_count` to control in-flight messages.

### Dead Letter Exchange (DLX)

Messages dead-letter when: rejected (nack/reject with `requeue=False`), expired (TTL), queue overflow (max-length), or delivery limit exceeded (quorum queues, default 20).

```bash
rabbitmqctl set_policy DLX ".*" \
  '{"dead-letter-exchange":"dlx.exchange","dead-letter-routing-key":"dlx.key"}' \
  --apply-to queues
```

## Anti-Patterns

| Anti-Pattern | Why It Fails | Instead |
|---|---|---|
| Classic queues for production data | No replication; single node failure loses messages | Use quorum queues |
| `autoAck=true` for critical workloads | Messages lost if consumer crashes before processing | Use manual ack with prefetch |
| One connection per publish | TCP connections are expensive | Pool connections; use channels for concurrency |
| `prefetch_count=0` (unlimited) | Consumer OOM; unfair distribution | Set prefetch 10-300 based on processing speed |
| Ignoring delivery limits | Poison messages loop forever on classic queues | Use quorum queues (default limit 20) or DLX |
| CQv1 config on 4.0+ | Prevents node startup | Remove `classic_queue.default_version = 1` |
| `force_reset` on 4.1+ | Deprecated; incompatible with Khepri | Use proper node removal procedures |
| Publishing and consuming on same connection | Flow control on one direction affects the other | Separate connections for publishing and consuming |

## Reference Files

- `references/architecture.md` -- Exchange types, queue types (quorum, classic, streams), Khepri internals, clustering, peer discovery, protocols, virtual hosts, connections/channels, super streams, stream deduplication
- `references/best-practices.md` -- Queue type selection guide, producer tuning (confirms, batching), consumer tuning (prefetch, ack modes), DLX patterns, TTL strategies, security hardening, Prometheus monitoring, migration from 3.13 to 4.x, Kubernetes deployment
- `references/diagnostics.md` -- Memory and disk alarms, flow control, queue buildup, network partitions, quorum queue leader issues, connection/channel leaks, TLS problems, Khepri migration issues, CLI tool reference (rabbitmqctl, rabbitmq-diagnostics, rabbitmq-queues, rabbitmq-streams, rabbitmqadmin v2)

## Cross-References

- The `overview` skill -- cross-broker comparisons and event-driven architecture design

## Diagnostic Scripts

Ready-made rabbitmqctl/rabbitmq-diagnostics bundles (run on a cluster node) in `scripts/`, numbered by investigation order. All read-only.

- `scripts/01-node-health.sh` -- Alarms (publisher-blocking!), health checks, quorum-critical queues
- `scripts/02-queue-depths.sh` -- Depth/consumer/memory ranking, zero-consumer backlogs
- `scripts/03-connections-channels.sh` -- Connection/channel leak audit, flow-controlled publishers