Message time-to-live (TTL) controls how long a message stays in a queue before ApsaraMQ for RabbitMQ discards it. Use message TTL to automatically clean up unconsumed messages and prevent queue buildup.
How it works
When a message remains in a queue longer than the configured TTL, ApsaraMQ for RabbitMQ removes it. What happens next depends on whether a dead-letter exchange is configured:
No dead-letter exchange configured: The message is permanently discarded. It cannot be delivered to consumers or retrieved through
basic.get.Dead-letter exchange configured: The message is routed to the dead-letter exchange, which forwards it to the bound dead-letter queue. Retrieve expired messages from the dead-letter queue for inspection or reprocessing. For details, see Dead-letter exchanges.
Use cases
Message TTL prevents message accumulation during traffic spikes. If expired messages do not need to be stored, set a TTL to discard them automatically rather than letting them build up in the queue.
Key concepts
Per-queue TTL vs. per-message TTL
ApsaraMQ for RabbitMQ supports two levels of TTL:
| Level | Scope | Argument | Value type |
|---|---|---|---|
| Per-queue | Applies to all messages in the queue | x-message-ttl | Non-negative integer (milliseconds) |
| Per-message | Applies to a single published message | expiration | String representing a non-negative integer (milliseconds) |
When both are set, the lower value takes effect.
ApsaraMQ for RabbitMQ does not support setting message TTL through thepolicyparameter of therabbitmqctltool. Use thex-message-ttlqueue argument or theexpirationmessage property instead.
TTL with delayed messages
For delayed messages, the actual TTL is calculated as:
Actual TTL = min(per-message TTL, per-queue TTL) + delay timeFor more information, see Delayed messages.
Maximum TTL value
The maximum TTL value equals the scheduled interval for sending scheduled messages on the instance.
TTL set to zero
Setting TTL to 0 causes messages to be discarded or forwarded to the dead-letter exchange unless a consumer receives them immediately.
Set message TTL
Set per-queue TTL in the console
Specify the message TTL when creating a queue in the ApsaraMQ for RabbitMQ console. For details, see Manage queues.
Set per-queue TTL through the API
Call the CreateQueue operation in OpenAPI Explorer to create a queue with message TTL configured.
Set TTL with an open source RabbitMQ SDK
Use any supported SDK to set TTL at the queue level or message level.
The following Java examples show how to set x-message-ttl during queue declaration and expiration on individual messages.
Per-queue TTL (applies to all messages in the queue):
Map<String, Object> args = new HashMap<String, Object>();
// Set TTL to 1000 milliseconds (1 second) for all messages in this queue
args.put("x-message-ttl", 1000);
channel.queueDeclare("myqueue", false, false, false, args);Per-message TTL (applies to a single published message):
byte[] messageBodyBytes = "test".getBytes();
AMQP.BasicProperties properties = new AMQP.BasicProperties.Builder()
// Set TTL to 1000 milliseconds (1 second) for this message only
.expiration("1000")
.build();
channel.basicPublish("my-exchange", "my-routing-key", properties, messageBodyBytes);When both per-queue and per-message TTL are set, the lower value takes effect.
Replace the exchange name, routing key, and TTL values with your actual configuration.
What's next
Dead-letter exchanges -- Handle expired messages instead of discarding them
Delayed messages -- Schedule messages for future delivery
Supported SDKs -- Find SDK examples in other languages