Major version upgrade for TCP client SDKs - ApsaraMQ for RocketMQ

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). These upgrades add message-based load balancing, more dashboard metrics, and full message trace support for scheduled, delayed, and transactional messages.

Before you upgrade, verify that your environment meets all eligibility requirements listed below.

Upgraded SDK versions

Protocol	Language	New version
TCP	Java	V2.x.x.Final
TCP	C++	V3.x.x

Before you upgrade

Review the following constraints to determine whether your environment supports the upgrade. The Java and C++ SDKs have different requirements.

Region availability

TCP client SDK for Java V2.x.x.Final: Available only in the following regions: China (Hangzhou), China (Qingdao), China (Beijing), China (Zhangjiakou), China (Hohhot), China (Shenzhen), China (Chengdu), China (Hong Kong), Germany (Frankfurt), and Indonesia (Jakarta).
Important
Do not upgrade to V2.x.x.Final in any other region. The SDK cannot connect to ApsaraMQ for RocketMQ in unsupported regions.
TCP client SDK for C++ V3.x.x: Available in all regions.

Network requirements

TCP client SDK for Java V2.x.x.Final: Supports virtual private cloud (VPC) access only.
Important
If your ApsaraMQ for RocketMQ instance uses the classic network, do not upgrade to V2.x.x.Final. Classic network access is not supported, and the upgrade breaks connectivity to your instance.
TCP client SDK for C++ V3.x.x: No network restrictions.

Namespace requirements

Both upgraded SDKs require instances with namespaces. If your instance does not contain a namespace, do not upgrade.

Note

All Message Queue for Apache RocketMQ 5.x instances contain namespaces by default. To check a Message Queue for Apache RocketMQ 4.x instance, go to the Instance Details page in the ApsaraMQ for RocketMQ console and look for the namespace field in the Basic Information section.

What changes after the upgrade

The following table summarizes the differences between the old and new SDK versions.

Feature	Old versions (Java V1.x.x.Final / C++ V2.x.x or V1.x.x)	New versions (Java V2.x.x.Final / C++ V3.x.x)
Load balancing	Queue-based	Message-based
Dashboard metrics	Basic (messages sent, received, accumulated)	Timing and success rate metrics across the full messaging lifecycle (see Dashboard metrics)
Message traces	No traces for scheduled, delayed, or transactional messages	Full trace support with OpenTelemetry (see Message traces)

Load balancing

The old SDK versions use queue-based load balancing, which has two known limitations:

If the number of consumers exceeds the number of queues, some consumers cannot receive messages.
Some consumers cannot consume messages as expected or consume messages at a low speed, while other consumers remain idle. This can cause message accumulation.

The new SDK versions use message-based load balancing, which distributes messages more evenly across consumers and eliminates both issues.

Dashboard metrics

The old SDK versions provide basic metrics only: messages sent, messages received, and messages accumulated.

The new SDK versions add timing and success rate metrics across the full messaging lifecycle, improving visibility into production and consumption performance.

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 currently being processed on the consumer client, with no success response returned yet.
Ready messages	Messages ready for consumption on the ApsaraMQ for RocketMQ broker. Reflects the number of unprocessed messages.
Ready message queue time	Time elapsed since the earliest ready message entered the queue. A high value indicates processing delays, which is critical for time-sensitive workloads.
Message processing time	Time to consume a message in a group.
Wait to process time	Time between when a consumer in a group receives a message and when it starts processing.
Consumption messages each protocol	Proportion of messages consumed over each protocol type relative to total consumed messages.

Instance top 20 rankings

These metrics identify the highest-impact groups and topics across your instance:

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 time between message receipt and processing 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 old SDK versions cannot query traces for scheduled, delayed, or transactional messages and do not include message accumulation data in trace results.

The new SDK versions improve trace capabilities:

Trace query results include message consumption data.
Traces can be filtered by exception, failure, and duration.
Scheduled, delayed, and transactional message traces are supported.
OpenTelemetry is integrated throughout the trace query process.

New trace parameters

The upgraded SDKs add the following parameters to trace query results:

Parameter	Description
AccessKey	AccessKey ID of your Alibaba Cloud account or RAM user. Required for authentication when accessing ApsaraMQ for RocketMQ resources through SDKs or API operations.
ReachServer	Time when the message arrived at the ApsaraMQ for RocketMQ broker.
PresetDeliverAt	Scheduled delivery time for a scheduled message.
ActualAvailableAt	Time when a scheduled message was delivered and became ready for consumption.
Available Time	Time when the message became ready for consumption.
Commit/RollbackTime	Time when a transactional message was committed or rolled back.
Arrive at Consumer At	Time when the message arrived at the consumer client.
Wait Duration before Processing	Time between message arrival at the consumer client and thread pool allocation for processing.