In distributed systems, resource contention means that not all messages can be processed immediately. Priority messages let producers assign a numeric priority to each message so that ApsaraMQ for RocketMQ delivers more urgent messages first when consumers fall behind.
Prerequisites
Before you begin, make sure you have:
Instance version 5.0-rmq-20260304-1 or later.
-
Client gRPC SDK:
Java SDK 5.2.0 or later.
Other language SDKs: to be released.
Use cases
When messages of different urgency levels share the same consumer, priority messages let you flag the most critical ones so the system processes them first during congestion.
Priority ordering only takes effect when messages accumulate — that is, when consumers cannot keep up with producers. If the system is not congested, all messages are delivered immediately regardless of priority. If your workload rarely produces a backlog, consider using separate topics per priority class instead.
AI computing resource scheduling
Graphics Processing Unit (GPU) and Neural Processing Unit (NPU) resources are scarce and scheduling is expensive. Use priority messages to control which tasks get resources first when demand spikes:
By task type: Assign higher priority to production inference requests (real-time user-facing) than to offline training or experimental model runs.
By batch size: Small quick-validation jobs can take high priority to free up resources fast; large-scale pretraining runs can be deprioritized.
By deadline: Tasks with strict time requirements — such as real-time updates for autonomous driving models — get the highest priority.
API rate limiting
When messages from multiple business lines (order processing, status sync, logging) share the same consumer under a third-party account-level rate limit, priority messages make sure order-related messages are processed before lower-stakes operations. This prevents payment or activation delays when the rate limit is reached.
Marketing push notifications
In social platforms or store management systems sending to large audiences, assign higher priority to time-sensitive messages (such as real-time customer service exchanges) and lower priority to marketing and bulk notifications.
How it works
Producers assign a numeric priority to each message before sending. Under message accumulation, ApsaraMQ for RocketMQ delivers messages to consumers in descending priority order, on a best-effort basis.
The producer sets the message priority using message properties — for example,
message.setPriority(int level).The broker writes each message to a per-priority queue within the topic. Each priority level maps to a dedicated queue.
When a consumer fetches messages, it pulls from the highest-priority queue first.
Priority ordering is strict within a single broker node — high-priority messages are always consumed first on that node. Global ordering across multiple brokers is not guaranteed. In distributed deployments, brokers are consumed in parallel, so the overall effect is best-effort prioritization.
Limits
Priority range: Integer from 0 to 9, where higher values mean higher priority.
Topic-level ceiling: Each topic has a configurable maximum priority (default: 9). To change the ceiling, submit a support ticket or contact your administrator.
When high-priority messages arrive faster than they are consumed, low-priority messages may be delayed indefinitely. ApsaraMQ for RocketMQ mitigates this by cycling through sub-queues during each delivery round, so low-priority messages eventually get processed. However, under sustained heavy load from high-priority producers, expect significant delays for low-priority traffic.
Best practices
Reduce maxCacheMessageCount for PushConsumer
The PushConsumer pre-fetches messages into a local cache before delivering them to the message listener. Messages in this local cache are not sorted by priority — they are held in the order they were fetched from the broker. If the cache is large, high-priority messages may sit behind low-priority ones already in the cache, bypassing the broker's priority ordering.
Keep maxCacheMessageCount small so that unprocessed messages stay on the broker, where priority ordering is enforced, rather than accumulating in the unsorted local cache.
Use concurrent delivery for priority consumer groups
Priority-based delivery breaks send order, which conflicts with ordered message delivery. Set the deliveryOrderType of the ConsumerGroup to Concurrently when consuming priority messages.