How RocketMQ NameServer Works: Registration, Heartbeats, and Failover

1 About NameServer

In the previous article we introduced RocketMQ's basic components—NameServer, Broker, Producer, and Consumer. NameServer acts as the service registry for RocketMQ, similar to Zookeeper for Kafka, managing cluster metadata (IP, port, router info) and must be started before any Broker.

2 NameServer Operation Flow

2.1 Registration

When a Broker starts, it establishes a long connection with the NameServer and sends a heartbeat every 30 seconds. The heartbeat includes the Broker's IP address, port, and router information, which is then registered in the NameServer.

The core data structure used for registration is:

HashMap<String BrokerName, BrokerData> brokerAddrTable

The key of the HashMap is the Broker name, storing the properties of a Broker service.

The value is an object with the following fields:

cluster (String): the name of the cluster the Broker belongs to.

broker (String): the Broker's name.

brokerAddress (HashMap): a list of the Broker's IP addresses, including one Master and multiple Slaves.

Example JSON representation:

<code>{
    "Broker-A": {
        "cluster": "Broker-Cluster",
        "brokerName": "Broker-A",
        "brokerAddress": {
            "0": "192.168.0.1:1234",
            "1": "192.168.0.2:1234",
            "2": "192.168.0.3:1234"
        }
    }
}</code>

2.2 Registration Information Update

When a Topic is added, modified, or deleted, the Broker must re‑register the updated information to the NameServer.

Creating a new Topic: the Broker sends registration info, and the NameServer creates a new QueueData object for each Master Broker.

Modifying a Topic: the NameServer first deletes the old QueueData and then adds a new one.

Deleting a Topic: the corresponding QueueData is removed.

The core data structure for topic registration is:

HashMap<String topic, List<QueueData>> topicQueueTable

The key is the Topic name, storing all its attributes.

The value is a list of QueueData objects, one per Master Broker.

Each QueueData contains:

brokerName (String): broker name.

readQueueNums (Long): number of read queues.

writeQueueNums (Long): number of write queues.

perm (Integer): permission flags (PRIORITY=3, READ=2, WRITE=1, INHERIT=0).

topicSyncFlag (Long): synchronization marker.

Example JSON for a Topic:

<code>{
  "topic-test": [
    {
      "brokerName": "Broker-A",
      "readQueueNums": 37,
      "writeQueueNums": 37,
      "perm": 6,
      "topicSyncFlag": 12
    },
    {
      "brokerName": "Broker-B",
      "readQueueNums": 37,
      "writeQueueNums": 37,
      "perm": 6,
      "topicSyncFlag": 12
    }
  ]
}</code>

2.3 Exception Cleanup

If a Broker crashes, its stale information must be removed from the NameServer to keep the registry accurate.

Each Broker sends a heartbeat to the NameServer every 30 seconds.

The NameServer updates the lastUpdateTimestamp field in the brokerLiveTable upon receiving a heartbeat.

A scheduled task runs every 10 seconds to scan brokerLiveTable .

If the time difference between the current time and lastUpdateTimestamp exceeds 120 seconds, the Broker is considered dead and removed from the registration table.

The core data structure for tracking live brokers is:

HashMap<String BrokerAddr, BrokerLiveInfo> brokerLiveTable

lastUpdateTimestamp (Long): timestamp of the last heartbeat.

dataVersion (DataVersion): version of the data.

channel (Channel): Netty channel for I/O.

haServerAddr (String): master address (empty on first request, filled after slave registration).

2.4 Message Production and Consumption

After the above steps, the NameServer acts as the "central brain" for routing. Producers and consumers interact as follows:

Producer/Consumer establishes a long connection with the NameServer.

Every 30 seconds they fetch the latest router information and cache it locally.

When a Producer sends a message (e.g., to topic-test ), it looks up the topicQueueTable to find the Broker name(s) for that topic.

Using the Broker name, it queries the brokerAddressTable to obtain the actual Broker IP addresses (typically one Master and several Slaves).

The Producer then connects to a selected Broker and sends the message; the Consumer follows the same steps to receive messages.

3 Summary

NameServer manages cluster metadata; it must be started before any Broker.

Broker registers with NameServer via a heartbeat every 30 seconds, reporting its IP, port, and Topic information.

A scheduled task scans the live‑broker table every 10 seconds; brokers missing heartbeats for over 120 seconds are removed.

Producers retrieve Broker addresses from NameServer, select a Broker based on load‑balancing, and send messages.

Consumers similarly fetch Broker lists, connect, and consume messages, refreshing the routing info every 30 seconds.