During cross-region replication, consumer groups in the source and destination instances process messages at different rates. If a failover occurs, consumers that reconnect to the destination instance must resume from the correct offset to avoid reprocessing large volumes of messages. Consumer progress synchronization in Global Replicator keeps committed offsets aligned between your source and destination ApsaraMQ for RocketMQ instances, so consumers pick up where they left off after a failover.
How it works
Global Replicator periodically checks the committed offsets of each consumer group in the source instance and replicates them to the matching consumer group in the destination instance. Synchronization applies only to consumer groups that meet both of the following conditions:
The group exists in both the source and destination instances with the same name.
The group subscribes to the same topics in both instances.
Progress is replicated asynchronously, so a delay of minutes can occur between when a consumer commits an offset in the source instance and when that offset appears in the destination instance. After a failover, some messages may be consumed again. Design your consumers to handle duplicate messages idempotently -- for example, deduplicate based on message ID or a business-level unique key before applying side effects.
One-way vs. two-way synchronization
| Dimension | One-way synchronization | Two-way synchronization |
|---|---|---|
| Direction | Source to destination only | Switchable between source-to-destination and destination-to-source |
| Auto sync | Supported. Syncs every 10 seconds across all topic mappings. | Not supported. Manual sync only. |
| Sync condition | Auto sync requires the destination consumer group to be online. Manual sync works regardless. | Manual sync from destination to source requires both groups to be actively consuming, and the source group's progress must be behind the destination group's progress. |
Configure one-way consumer progress synchronization
Before you begin, make sure you have a Global Replicator synchronization task configured, with consumer groups of the same name and the same topic subscriptions deployed on both the source and destination instances.
One-way synchronization supports both automatic and manual sync modes:
Auto sync: After you turn on Automatically Update Consumer Progress, the system syncs consumer progress every 10 seconds across all topic mappings between the source and destination instances. Auto sync skips consumer groups that are offline in the destination instance.
Manual sync: Works regardless of whether the destination consumer group is online or offline.
The first time you turn on Consumer Progress Synchronization, Automatically Update Consumer Progress is turned on by default.
To configure one-way consumer progress synchronization:
Log on to the ApsaraMQ for RocketMQ console.
In the top navigation bar, select the region where your synchronization task resides, such as China (Hangzhou).
In the left-side navigation pane, click Global Replicator. Find the task you want to configure.
On the Basic Task Information page, click Consumer Progress Synchronization in the left-side navigation pane.
Turn on Consumer Progress Synchronization.
Choose a synchronization method:
Auto sync: Turn on Automatically Update Consumer Progress.
Manual sync: Turn off Automatically Update Consumer Progress, then click Quick Synchronization. In the confirmation dialog, click OK.
Configure two-way consumer progress synchronization
Two-way synchronization supports manual sync only. Use manual sync when a business exception occurs to reduce duplicate message consumption.
To sync progress from the destination to the source, both of the following conditions must be met:
Both the source and destination consumer groups are actively consuming messages.
The source consumer group's progress is behind the destination consumer group's progress.
To configure two-way consumer progress synchronization:
Log on to the ApsaraMQ for RocketMQ console.
In the top navigation bar, select the region where your synchronization task resides, such as China (Hangzhou).
In the left-side navigation pane, click Global Replicator. Find the task you want to configure.
On the Basic Task Information page, click Consumer Progress Synchronization in the left-side navigation pane.
Turn on Consumer Progress Synchronization.
(Optional) To change the sync direction, click Switch Synchronization Direction. In the confirmation dialog, click OK.
Click Quick Synchronization. In the confirmation dialog, click OK.
FAQ
Why are some consumer groups not synchronized?
Only consumer groups that share the same name and subscribe to the same topics in both the source and destination instances are eligible for synchronization. Verify that the group name and topic subscriptions match exactly in both instances.
For one-way tasks with auto sync enabled, also check whether the consumer group in the destination instance is online. Auto sync skips offline groups.
How do I handle duplicate messages after a failover?
Consumer progress sync has an inherent delay of minutes. After a failover, consumers may reprocess messages that were already consumed in the source instance. Deduplicate based on message ID or a business-level unique key before applying side effects.