Topic throttling is a fine-grained traffic control capability provided by ApsaraMQ for Kafka. By configuring independent rate limits for production and consumption on individual topics, you can implement differentiated traffic control across different business workloads in multi-tenant shared clusters and burst traffic protection scenarios, ensuring the stability of core business services.
Overview
Topic throttling is a fine-grained traffic control capability provided by ApsaraMQ for Kafka. By configuring independent rate limits for production, consumption, and cold data consumption on individual topics, you can implement differentiated traffic control across different business workloads in multi-tenant shared clusters, burst traffic protection, and cost control scenarios, ensuring the stability of core business services.
Compared to traditional global throttling, topic-level throttling offers the following advantages:
Business isolation: Traffic between different topics is independent, preventing a traffic spike from one topic from impacting the entire cluster.
Precise control: Supports separate control of production and consumption rates at the topic dimension.
Limits
Only Kafka Serverless instances support topic throttling, and the instance version must be 3.7.1.1 or later.
If you need to use this feature, please submit a ticket to apply.
Core concepts
Throttling types
Topic throttling supports the following traffic control dimensions:
Throttling type | Description | Use case |
Production throttling | Limits the rate at which messages are written to a specified topic. | Prevents a producer from causing a burst of high traffic that overwhelms the cluster. |
Consumption throttling | Limits the rate at which hot data is pulled from a specified topic. | Controls the consumer read rate to prevent consumer overload. |
Throttling granularity
Throttling is configured at the topic level as the smallest unit of granularity. When calculating the actual throttling threshold, the system automatically considers the partition distribution of that topic across brokers, ensuring that throttling policies take effect accurately at the cluster level.
How it works
Scheduling mechanism
After topic throttling is enabled, the system periodically scans and updates the throttling parameters for each topic. There is an estimated delay of 5 to 10 seconds before topic throttling parameters take effect.
Throttling calculation logic
The actual throttling threshold is calculated based on the following factors:
Total number of partitions in the topic: Used as the baseline for quota distribution.
Number of leader partitions on the current broker: Determines the proportion of throttling that broker is responsible for.
For example, if a topic has a production throttle of 10 MB/s, a total of 10 partitions, and the current broker hosts 3 leader partitions, then the production throttle for that topic on that broker is approximately 3 MB/s.
Impact of throttling on message writes
Understanding system behavior after throttling is triggered is critical for assessing business impact.
Throttling detection
When a producer sends messages, the system continuously tracks the request byte size and compares it against the current quota. If traffic exceeds the quota, throttling is triggered.
Behavior after throttling is triggered
When a topic reaches its production throttle threshold, the system does not directly reject message writes. Instead, it takes the following actions:
Connection throttling: Throttles the current client connection and pauses receiving new requests from that connection.
Return wait time: Informs the client in the response of the wait time required (in milliseconds).
Messages are still processed: Messages in the current request are still written to the topic normally and are not lost due to throttling, except in special cases.
Automatic client backoff: After receiving a throttling response, the client backs off for the wait time specified by the server before resuming subsequent requests.
Special case:
If traffic is excessively high and the throttle value is set too low, data can be held back on the client side for an extended period. If the backpressure duration exceeds the client-side delivery.timeout.ms setting (default: 2 minutes), the client process may automatically exit. In this case, in-flight messages may not be acknowledged, and if the client cannot resume, message loss may occur.
Key conclusions
Behavior | Description |
Will messages be discarded? | Messages may be lost if backpressure duration exceeds the client-side delivery.timeout.ms setting. |
What does the client receive? | The server returns the required wait time (throttle_time_ms). |
How does it affect business? | Producers experience increased write latency, but data is not lost. |
How does the system recover after throttling is lifted? | The client automatically resumes after the specified wait time without manual intervention. |
Typical use cases
Multi-tenant traffic isolation
In scenarios where multiple teams or business units share the same Kafka cluster, setting differentiated throttling thresholds for topics of different tenants effectively prevents a traffic spike from one tenant from degrading service quality for others.
Core business protection
By configuring reasonable throttle limits for critical business topics, you can keep write rates within safe bounds even during upstream or downstream traffic spikes, preventing brokers from experiencing response delays or jitter due to transient high loads.
Consumer rate control
For scenarios with limited consumer capacity or capacity-sensitive downstream systems, you can actively control the consumption rate through pull throttling to prevent consumers from being overwhelmed.
Cold data retrieval cost control
By setting independent throttling parameters for cold data retrieval, you can control the read pressure on the storage layer during historical data retrieval or offline analysis, avoiding impact on online hot data read/write performance.
Configuration guide
Prerequisites
An ApsaraMQ for Kafka instance is created.
The instance version supports topic throttling (Serverless instances support this by default).
You have instance-level management permissions.
A topic is created.
Enable topic throttling
Log on to the ApsaraMQ for Kafka console.
On the Overview page, select a region in the Resource Distribution section.
On the Instances page, click the name of the target instance.
On the Instance Details page, navigate to Instance Info / Configuration, and enable the Topic Throttling toggle.
Configure topic-level throttling parameters
Step 1: Go to the Topic management page
On the Topics page, click the name of the target topic.
On the Topic Details page, edit the production throttle or consumption throttle.
Step 2: Set throttling thresholds
On the Topic Details page, find and fill in the following configuration items:
Parameter | Unit | Description |
Production throttle | MB/s | The maximum production rate for this topic. For example: 10 MB/s. This rate applies to business traffic only and does not include replica traffic. |
Consumption throttle | MB/s | The maximum rate for pulling hot data from this topic. |
Configuration example:
If the typical production peak for a topic is approximately 8 MB/s, you can set the production throttle to 10 MB/s to reserve buffer capacity and protect against traffic spikes.
Note:
If a throttle threshold is not configured, no throttling is applied to that dimension.
After modifying the configuration, you must wait for the next scheduler execution for the changes to take effect.
Verify that throttling takes effect
After configuration, you can verify throttling using the following methods:
Check monitoring metrics: On the Instance Details / Observability / Dashboard page in the console, view the production throttle time for the instance.
Client observation: If throttling is triggered on the producer side, the response will contain the throttle_time_ms field. You can observe the corresponding wait time in the client logs.
FAQ
Will messages being sent be discarded when topic throttling is triggered?
If traffic is excessively high and the throttle value is set too low, data can be held back on the client side for an extended period. If the backpressure duration exceeds the client-side delivery.timeout.ms setting (default: 2 minutes), the client process may automatically exit. In this case, in-flight messages may not be acknowledged and could be lost.
Why is topic traffic higher than the configured threshold?
Throttling values are not 100% precise. Instantaneous write or consume rates may exceed the configured threshold. Additionally, throttling is not a hard limit — it does not reject messages already in-flight — so the actual traffic may temporarily exceed the configured threshold.
Why is topic traffic lower than the configured threshold?
The throttling threshold is shared across all leader partitions of the topic. If traffic distribution is uneven (for example, messages are sent with a specific key or to specific partitions, causing message skew), the broker nodes hosting the hot partitions may reach the cluster throttle threshold first, triggering throttling and causing overall topic traffic to fall below the configured threshold.
Why hasn't throttling taken effect after configuration?
Check whether the global switch on the Instance Details page (Enable Topic Throttling toggle) is enabled.
Configuration updates have an estimated propagation delay of 5 to 10 seconds.
How do I evaluate a reasonable throttling threshold?
We recommend evaluating based on the following data:
The historical traffic peak for the topic (viewable on the monitoring page in the console).
The processing capacity of the downstream consumers.
The overall bandwidth and disk I/O capacity of the cluster.
It is generally recommended to set the throttle threshold to 1.2 to 1.5 times the historical peak — this provides a buffer while still offering protection in extreme situations.