What’s New in RocketMQ 5.0 SDK? Unified API, gRPC, and Enhanced Observability

Unified API and Client Architecture

RocketMQ 5.0 introduces a brand‑new client SDK that uses gRPC as the transport layer. The API is defined as a single specification that includes method signatures, concrete behavior contracts, and a builder‑pattern for immutable client objects. Exception handling is standardized across all operations.

The SDK defines four client roles:

Producer

Push Consumer – uses the pop mechanism and automatically caches received messages.

Simple Consumer – gives the application full control over receive, ack and visibility‑time adjustments.

Pull Consumer – still under development.

Message Types

Four mutually exclusive message categories are now part of the topic metadata:

NORMAL – regular messages.

FIFO – ordered delivery enforced by a message group identifier; messages in the same group are consumed in send order.

TRANSACTIONAL – a set of messages that can be committed or rolled back as a single transaction.

DELAY – timestamp‑based delayed delivery with millisecond precision, replacing the previous level‑based delay.

The SDK validates that the message type matches the topic’s configured type and rejects mismatches at send time.

Client Startup Enhancements

During initialization the client proactively fetches routing information for all topics that the application intends to use. This eliminates the cold‑start latency of the first send and enables fast‑fail behavior when a topic does not exist.

A bidirectional Telemetry channel is established over gRPC. The server can push configuration updates to the client, and the client reports its local configuration and health status back to the server. Failure to create this channel aborts the client startup.

Producer Workflow

When send() is invoked, the producer checks the local routing cache. If the cache is empty it fetches the routing on‑the‑fly. The producer then:

Selects a queue from the routing data.

Verifies that the message’s type matches the topic’s declared type.

Attempts delivery via an asynchronous gRPC call.

If the call fails, retries up to the user‑configured limit, rotating to the next queue on each attempt.

Both synchronous and asynchronous send APIs are thin wrappers around the same asynchronous implementation, ensuring a uniform code path.

Consumer Workflows

Push Consumer continuously pulls messages from the broker, stores them in a local cache, and processes them while respecting a configurable cache‑size limit to avoid memory pressure. If the cache is full, the pull loop pauses until space becomes available.

Simple Consumer lets the application explicitly call receive(), decide when to ack() or modify the message’s visibility timeout, and optionally delay processing.

Consumption can be:

Ordered – messages belonging to the same message group are processed sequentially; a later message is not delivered until the previous one is successfully acked. Virtual queues are used internally to isolate groups and prevent cross‑group blocking.

Concurrent – messages are processed in parallel without ordering guarantees.

Observability Improvements

Shaded Logback : The SDK bundles a shaded version of Logback (named rocketmq.logback.xml) and routes all logs through SLF4J, preventing conflicts with user‑provided Logback configurations.

Tracing : Built on the OpenTelemetry messaging model. Each send or receive operation creates a Span linked via parent‑child or link relationships, providing end‑to‑end visibility of a message’s lifecycle. Applications can attach their own span context to integrate RocketMQ spans into existing traces.

Metrics : Also OpenTelemetry‑based. The SDK emits metrics such as producer latency, consumer processing time, cache size, retry counts, and dead‑letter statistics. Metrics are collected via manual instrumentation; the server supplies the collector endpoint during the Telemetry handshake, and the client pushes metrics to that endpoint.

Repository

https://github.com/apache/rocketmq-clients