Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 37 ยท Queues and Exchanges

Queue Arguments: TTL, Length and Dead Letters

Use RabbitMQ queue arguments and policies: message and queue TTL, length limits, overflow behavior, dead letter exchanges and the x-death header.

Queues take optional arguments that change their behavior: messages can expire, queues can be capped, and messages that cannot be processed can be sent to another exchange instead of vanishing. These features turn a plain queue into a robust building block, and they are the basis of retry and delay patterns.

Argument names and policies below match real RabbitMQ. Declarations and rabbitmqctl commands are read-only. The runnable blocks are stand-ins that use a simulated clock, so their timing is fake and deterministic.

Where arguments go

Arguments are passed in the arguments table of queue_declare, or applied by a policy:

Python
# real pika code, read-only
channel.queue_declare(
    "jobs",
    durable=True,
    arguments={
        "x-queue-type": "quorum",
        "x-message-ttl": 60000,            # milliseconds
        "x-max-length": 10000,
        "x-dead-letter-exchange": "jobs.dead",
    },
)

Arguments are fixed at declaration: changing them later needs a new queue. A policy is a rule stored on the broker that applies settings to every queue or exchange whose name matches a regular expression. Policies can be changed at any time, which makes them the preferred way to manage most of the settings below.

Terminal
rabbitmqctl set_policy jobs-limits "^jobs\." \
  '{"message-ttl":60000,"max-length":10000,"dead-letter-exchange":"jobs.dead"}' \
  --apply-to queues

Note that policy keys drop the x- prefix. If both a policy and an argument set the same key, the argument wins for some keys and the lower value wins for others (for example TTL and max length take the smaller one), so check the docs for the keys you use.

Message TTL

A time-to-live removes messages that wait too long.

  • Per-queue: x-message-ttl applies to every message that enters the queue.
  • Per-message: the expiration property, a string of milliseconds, set by the publisher. When both exist the shorter time is used.

An expired message is dropped, or dead-lettered if a DLX is configured. In classic queues, per-message expiry is only checked at the head of the queue, so an expired message behind a long-lived one may stay until it reaches the head; per-queue TTL does not have that problem because every message shares the same TTL. TTL is a good fit for data that becomes useless, such as a "send this notification now" message that is pointless tomorrow.

Queue expiry

x-expires deletes the queue itself if it has been unused (no consumers, no basic_get, no redeclare) for the given number of milliseconds. It cleans up abandoned queues created by clients that vanished.

Length limits and overflow

x-max-length (message count) and x-max-length-bytes cap a queue. When the cap is hit, the x-overflow behavior decides what happens:

  • drop-head (default): the oldest message is dropped (or dead-lettered).
  • reject-publish: new messages are refused; publishers using confirms receive a nack.
  • reject-publish-dlx: like reject-publish, but the refused message is also dead-lettered.

drop-head suits "keep the latest N readings"; reject-publish suits systems where publishers should slow down instead of losing data.

Dead letter exchanges

A dead letter exchange (DLX) is an ordinary exchange. A queue with x-dead-letter-exchange sends a message there when it is "dead". A message dies when:

  1. a consumer rejects or nacks it with requeue=false;
  2. its TTL expires;
  3. the queue overflows and drops it (maxlen);
  4. a quorum queue's delivery limit is exceeded.

Optionally x-dead-letter-routing-key replaces the routing key; otherwise the original one is kept. The DLX routes the message like any other publish, usually into a "dead letter queue" that people or tools inspect.

flowchart LR
    X["jobs exchange"] --> Q["jobs queue<br/>ttl, max length, DLX"]
    Q -->|"consumer"| C["Worker"]
    Q -->|"rejected / expired / overflow"| DLX["jobs.dead exchange"]
    DLX --> DQ["jobs.dead queue"]

Dead lettering moves a message to another exchange instead of dropping it.

Dead-lettered messages carry an x-death header describing why and how often they died: reason, queue, exchange, routing keys, time and a count. Read it to build retry limits.

Simulating it

The stand-in uses a manual clock (now) so you can see TTL, max length and dead lettering without waiting.

Python TTL, max length and a dead letter queue (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

A retry and delay pattern with TTL and DLX

RabbitMQ has no built-in "retry in 30 seconds", but you can compose one. A retry queue has no consumers, a message TTL of 30 seconds, and a DLX pointing back at the main exchange. A failed job is published to the retry queue; after 30 seconds it expires and is dead-lettered into the main queue for another attempt. Using the x-death count, the worker can give up after a few tries and send the job to a final parked queue.

flowchart LR
    M["main queue"] -->|"worker fails job"| R["retry queue<br/>TTL 30s, no consumers"]
    R -->|"expires, DLX"| M
    M -->|"too many attempts"| P["parked queue"]

The retry queue is just a timer built from TTL plus dead lettering.

Python Retry with a ceiling (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Other useful arguments

  • x-max-priority: enables priorities on classic queues (keep the number small, such as 5 to 10, because each level costs resources).
  • x-single-active-consumer: only one consumer receives messages at a time; others stand by. Useful for strict ordering with automatic failover.
  • x-delivery-limit (quorum queues): max redeliveries before a message is dead-lettered or dropped.
  • x-max-age and x-max-length-bytes on streams: retention.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In which unit is x-message-ttl given?

    TTL values are in milliseconds, for both the queue argument and the per-message expiration property.
  2. 2. Which of these does NOT cause a message to be dead-lettered?

    A successful acknowledgement just removes the message. The other three are dead-letter reasons.
  3. 3. What does x-overflow=reject-publish do when the queue is full?

    reject-publish protects existing messages by refusing new ones; the default drop-head discards the oldest.
  4. 4. Why are policies often preferred over declaration arguments?

    Arguments are fixed at declaration, but a policy can be updated at any time and applies to all matching queues.

Summary

  • Queue arguments and policies add TTL, expiry, length limits and dead lettering.
  • TTL is in milliseconds; per-message expiration is a string.
  • Overflow can drop the oldest message or reject new publishes.
  • Rejected, expired, overflowed and over-delivered messages can be dead-lettered to a DLX; x-death records why.
  • TTL plus DLX builds retry and delay queues.

Next: The Direct Exchange