On October 18, 2021, ApsaraMQ for RocketMQ released major version upgrades for the TCP client SDK for Java (V2.x.x.Final) and the TCP client SDK for C++ (V3.x.x). The upgraded SDKs switch from queue-based to message-based load balancing, add detailed dashboard metrics for producers and consumers, and expand message trace capabilities to cover scheduled, delayed, and transactional messages.
Before you upgrade, verify that your environment meets all compatibility requirements described in this topic.
SDK versions
| Protocol | Language | Version |
|---|---|---|
| TCP | Java | V2.x.x.Final |
| TCP | C++ | V3.x.x |
Compatibility requirements
Review the following requirements before you upgrade. If your environment does not meet all conditions for your SDK language, do not upgrade.
Java SDK V2.x.x.Final
| Requirement | Constraint | If not met |
|---|---|---|
| Region | Available only in: China (Hangzhou), China (Qingdao), China (Beijing), China (Zhangjiakou), China (Hohhot), China (Shenzhen), China (Chengdu), China (Hong Kong), Germany (Frankfurt), and Indonesia (Jakarta). | Do not upgrade. The upgraded SDK cannot connect to ApsaraMQ for RocketMQ in unsupported regions. |
| Network | Supports only virtual private cloud (VPC) access. | Do not upgrade. The upgraded SDK cannot access instances over the classic network. |
| Namespace | Supports only instances that contain namespaces. | Do not upgrade. |
C++ SDK V3.x.x
| Requirement | Constraint | If not met |
|---|---|---|
| Region | Available in all regions. | No restriction. |
| Network | No restriction. | No restriction. |
| Namespace | Supports only instances that contain namespaces. | Do not upgrade. |
Check whether your instance contains a namespace
All Message Queue for Apache RocketMQ 5.x instances contain namespaces by default. To check a 4.x instance, go to the Basic Information section on the Instance Details page in the ApsaraMQ for RocketMQ console.
Feature changes
The following sections compare the previous major versions (Java V1.x.x.Final / C++ V2.x.x or V1.x.x) with the upgraded versions (Java V2.x.x.Final / C++ V3.x.x).
Load balancing
| Aspect | Before upgrade | After upgrade |
|---|---|---|
| Policy | Queue-based | Message-based |
| Behavior | Consumers are assigned to specific queues. If the number of consumers exceeds the number of queues, some consumers remain idle. Uneven queue assignments can also cause message accumulation. | Messages are distributed across consumers directly, which produces more balanced loads and eliminates idle consumers caused by queue-based assignment. |
Dashboard metrics
The upgraded SDKs report additional metrics on the dashboard. Before the upgrade, only basic metrics were available: received messages, sent messages, and accumulated messages.
Producer metrics
| Metric | Description |
|---|---|
| Send RT | Time to produce a message in a topic. |
| Send API call success rate | Success rate of message production in a topic. |
Consumer metrics
| Metric | Description |
|---|---|
| Avg consumption success rate | Success rate of message consumption in a specific instance. |
| Inflight messages | Messages being processed on the consumer client for which no success response has been returned. |
| Ready messages | Messages ready for consumption on the ApsaraMQ for RocketMQ broker. This reflects the number of unprocessed messages. |
| Ready message queue time | Time offset between the current point in time and the point in time when the earliest message is ready. A high value indicates a delay in processing ready messages. |
| Message processing time | Time to consume a message in a group. |
| Wait to process time | Duration between a consumer in a group receiving a message and starting to consume it. |
| Consumption messages each protocol | Proportion of messages consumed over each protocol type relative to total consumed messages. |
Instance top 20 metrics
These metrics show the top 20 groups or topics ranked by a specific dimension, helping you identify bottlenecks.
| Metric | Description |
|---|---|
| Ready message queue time per GroupID | Top 20 groups with the longest queuing duration for ready messages. |
| Consumer lag per GroupID | Top 20 groups with the largest number of accumulated messages. |
| Inflight messages per GroupID | Top 20 groups with the largest number of inflight messages. |
| Message processing time per GroupID | Top 20 groups with the longest consumption duration. |
| Message wait time per GroupID | Top 20 groups with the longest wait between message receipt and consumption start. |
| Send API call failure rate per Topic | Top 20 topics with the highest message production failure rate. |
| Consumption failure rate per GroupID | Top 20 groups with the highest message consumption failure rate. |
Message traces
The upgraded SDKs expand message trace capabilities in three areas:
Broader coverage: Trace queries now support scheduled messages, delayed messages, and transactional messages. Previously, traces of these message types could not be queried, and data related to message accumulation was not included in trace query results.
Richer filtering: Filter trace results by exceptions, failures, and durations. Message consumption data is now included in trace results.
OpenTelemetry integration: The entire message trace query process uses OpenTelemetry.
New trace parameters
The following parameters are added to trace query results:
| Parameter | Description |
|---|---|
| AccessKey | The AccessKey ID of your Alibaba Cloud account or RAM user, used for identity verification when calling ApsaraMQ for RocketMQ through SDKs or API operations. |
| ReachServer | Time when the message arrived at the ApsaraMQ for RocketMQ broker. |
| PresetDeliverAt | Preset delivery time for a scheduled message. |
| ActualAvailableAt | Time when a scheduled message becomes available for consumption. |
| Available Time | Time when a message becomes ready for consumption. |
| Commit/RollbackTime | Time when a transactional message is committed or rolled back. |
| Arrive at Consumer At | Time when the message arrives at a consumer client. |
| Wait Duration before Processing | Duration between message arrival at a consumer client and thread pool allocation for processing. |