rocketmq Documentation

1. Project Overview & Quickstart (apache/rocketmq) Copy Chapter

File: README.md Copy Chapter

Apache RocketMQ Copy Chapter

Apache RocketMQ is a distributed messaging and streaming platform with low latency, high performance and reliability, trillion-level capacity and flexible scalability.

It offers a variety of features:

• Messaging patterns including publish/subscribe, request/reply and streaming
• Financial grade transactional message
• Built-in fault tolerance and high availability configuration options based on DLedger Controller
• Built-in message tracing capability, also supports opentracing
• Versatile big-data and streaming ecosystem integration
• Message retroactivity by time or offset
• Reliable FIFO and strict ordered messaging in the same queue
• Efficient pull and push consumption model
• Million-level message accumulation capacity in a single queue
• Multiple messaging protocols like gRPC, MQTT, JMS and OpenMessaging
• Flexible distributed scale-out deployment architecture
• Lightning-fast batch message exchange system
• Various message filter mechanics such as SQL and Tag
• Docker images for isolated testing and cloud isolated clusters
• Feature-rich administrative dashboard for configuration, metrics and monitoring
• Authentication and authorization
• Free open source connectors, for both sources and sinks
• Lightweight real-time computing

Quick Start Copy Chapter

This paragraph guides you through steps of installing RocketMQ in different ways.
For local development and testing, only one instance will be created for each component.

Run RocketMQ locally Copy Section

RocketMQ runs on all major operating systems and requires only a Java JDK version 8 or higher to be installed.
To check, run java -version:

$ java -version
java version "1.8.0_121"

For Windows users, click here to download the 5.5.1 RocketMQ binary release,
unpack it to your local disk, such as D:\rocketmq.
For macOS and Linux users, execute following commands:

# Download release from the Apache mirror
$ wget https://dist.apache.org/repos/dist/release/rocketmq/5.5.1/rocketmq-all-5.5.1-bin-release.zip

# Unpack the release
$ unzip rocketmq-all-5.5.1-bin-release.zip

Prepare a terminal and change to the extracted bin directory:

$ cd rocketmq-all-5.5.1-bin-release/bin

1) Start NameServer

NameServer will be listening at 0.0.0.0:9876, make sure that the port is not used by others on the local machine, and then do as follows.

For macOS and Linux users:

### start Name Server
$ nohup sh mqnamesrv &

### check whether Name Server is successfully started
$ tail -f ~/logs/rocketmqlogs/namesrv.log
The Name Server boot success...

For Windows users, you need to set environment variables first:

• From the desktop, right click the Computer icon.
• Choose Properties from the context menu.
• Click the Advanced system settings link.
• Click Environment Variables.
• Add Environment ROCKETMQ_HOME="D:\rocketmq".

Then change directory to rocketmq, type and run:

$ mqnamesrv.cmd
The Name Server boot success...

2) Start Broker

For macOS and Linux users:

### start Broker
$ nohup sh mqbroker -n localhost:9876 &

### check whether Broker is successfully started, eg: Broker's IP is 192.168.1.2, Broker's name is broker-a
$ tail -f ~/logs/rocketmqlogs/broker.log
The broker[broker-a, 192.168.1.2:10911] boot success...

For Windows users:

$ mqbroker.cmd -n localhost:9876
The broker[broker-a, 192.168.1.2:10911] boot success...

Run RocketMQ in Docker Copy Section

You can run RocketMQ on your own machine within Docker containers,
host network will be used to expose listening port in the container.

1) Start NameServer

$ docker run -it --net=host apache/rocketmq ./mqnamesrv

2) Start Broker

$ docker run -it --net=host --mount type=bind,source=/tmp/store,target=/home/rocketmq/store apache/rocketmq ./mqbroker -n localhost:9876

Run RocketMQ in Kubernetes Copy Section

You can also run a RocketMQ cluster within a Kubernetes cluster using RocketMQ Operator.
Before your operations, make sure that kubectl and related kubeconfig file installed on your machine.

1) Install CRDs

### install CRDs
$ git clone https://github.com/apache/rocketmq-operator
$ cd rocketmq-operator && make deploy

### check whether CRDs are successfully installed
$ kubectl get crd | grep rocketmq.apache.org
brokers.rocketmq.apache.org                 2022-05-12T09:23:18Z
consoles.rocketmq.apache.org                2022-05-12T09:23:19Z
nameservices.rocketmq.apache.org            2022-05-12T09:23:18Z
topictransfers.rocketmq.apache.org          2022-05-12T09:23:19Z

### check whether operator is running
$ kubectl get pods | grep rocketmq-operator
rocketmq-operator-6f65c77c49-8hwmj   1/1     Running   0          93s

2) Create Cluster Instance

### create RocketMQ cluster resource
$ cd example && kubectl create -f rocketmq_v1alpha1_rocketmq_cluster.yaml

### check whether cluster resources are running
$ kubectl get sts
NAME                 READY   AGE
broker-0-master      1/1     107m
broker-0-replica-1   1/1     107m
name-service         1/1     107m

Apache RocketMQ Community Copy Chapter

• RocketMQ Streams: A lightweight stream computing engine based on Apache RocketMQ.
• RocketMQ Flink: The Apache RocketMQ connector of Apache Flink that supports source and sink connector in data stream and Table.
• RocketMQ APIs: RocketMQ protobuf protocol.
• RocketMQ Clients: gRPC/protobuf-based RocketMQ clients.
• RocketMQ Remoting-based Clients
  • RocketMQ Client CPP
  • RocketMQ Client Go
  • RocketMQ Client Python
  • RocketMQ Client Nodejs
• RocketMQ Spring: A project which helps developers quickly integrate Apache RocketMQ with Spring Boot.
• RocketMQ Exporter: An Apache RocketMQ exporter for Prometheus.
• RocketMQ Operator: Providing a way to run an Apache RocketMQ cluster on Kubernetes.
• RocketMQ Docker: The Git repo of the Docker Image for Apache RocketMQ.
• RocketMQ Dashboard: Operation and maintenance console of Apache RocketMQ.
• RocketMQ Connect: A tool for scalably and reliably streaming data between Apache RocketMQ and other systems.
• RocketMQ MQTT: A new MQTT protocol architecture model, based on which Apache RocketMQ can better support messages from terminals such as IoT devices and Mobile APP.
• RocketMQ EventBridge: EventBridge makes it easier to build an event-driven application.
• RocketMQ Incubating Community Projects: Incubator community projects of Apache RocketMQ, including logappender, rocketmq-ansible, rocketmq-beats-integration, rocketmq-cloudevents-binding, etc.
• RocketMQ Site: The repository for Apache RocketMQ website.
• RocketMQ E2E: A project for testing Apache RocketMQ, including end-to-end, performance, compatibility tests.

Learn it & Contact us Copy Chapter

• Mailing Lists: https://rocketmq.apache.org/about/contact/
• Home: https://rocketmq.apache.org
• Docs: https://rocketmq.apache.org/docs/quick-start/
• Issues: https://github.com/apache/rocketmq/issues
• Rips: https://github.com/apache/rocketmq/wiki/RocketMQ-Improvement-Proposal
• Ask: https://stackoverflow.com/questions/tagged/rocketmq

Contributing Copy Chapter

We always welcome new contributions, whether for trivial cleanups, big new features or other material rewards, more details see here.

License Copy Chapter

Apache License, Version 2.0 Copyright (C) Apache Software Foundation

Export Control Notice Copy Chapter

This distribution includes cryptographic software. The country in which you currently reside may have
restrictions on the import, possession, use, and/or re-export to another country, of encryption software.
BEFORE using any encryption software, please check your country's laws, regulations and policies concerning
the import, possession, or use, and re-export of encryption software, to see if this is permitted. See
http://www.wassenaar.org/ for more information.

The U.S. Government Department of Commerce, Bureau of Industry and Security (BIS), has classified this
software as Export Commodity Control Number (ECCN) 5D002.C.1, which includes information security software
using or performing cryptographic functions with asymmetric algorithms. The form and manner of this Apache
Software Foundation distribution makes it eligible for export under the License Exception ENC Technology
Software Unrestricted (TSU) exception (see the BIS Export Administration Regulations, Section 740.13) for
both object code and source code.

The following provides more details on the included cryptographic software:

This software uses Apache Commons Crypto (https://commons.apache.org/proper/commons-crypto/) to
support authentication, and encryption and decryption of data sent across the network between
services.

File: distribution/bin/README.md Copy Chapter

Operating system tuning Copy Section

Before deploying broker servers, it is highly recommended to run os.sh, which optimizes your operating system for better performance.

Notice Copy Chapter

os.sh should be executed only once with root permission. Copy Section

os.sh parameter settings are for reference purposes only. You can tune them according to your target host configurations. Copy Section

Start broker Copy Section

• Unix platform

  nohup sh mqbroker &

Shutdown broker Copy Section

sh mqshutdown broker

Start Nameserver Copy Section

• Unix platform

  nohup sh mqnamesrv &

Shutdown Nameserver Copy Section

sh mqshutdown namesrv

Update or create Topic Copy Section

sh mqadmin updateTopic -b 127.0.0.1:10911 -t TopicA

Update or create subscription group Copy Section

sh mqadmin updateSubGroup -b 127.0.0.1:10911 -g SubGroupA

File: docs/en/acl/Operations_ACL.md Copy Chapter

Access control list

Overview Copy Chapter

This document focuses on how to quickly deploy and use a RocketMQ cluster that supports the privilege control feature.

1. Access control features Copy Chapter

Access Control (ACL) mainly provides Topic resource level user access control for RocketMQ.If you want to enable RocketMQ permission control, you can inject the AccessKey and SecretKey signatures through the RPCHook on the Client side.And then, the corresponding permission control attributes (including Topic access rights, IP whitelist and AccessKey and SecretKey signature) are set in the configuration file of distribution/conf/plain_acl.yml.The Broker side will check the permissions owned by the AccessKey, and if the verification fails, an exception is thrown;
The source code about ACL on the Client side can be find in org.apache.rocketmq.example.simple.AclClient.java

2. Access control definition and attribute values Copy Chapter

2.1 Access control definition Copy Section

The definition of Topic resource access control for RocketMQ is mainly as shown in the following table.

2.2 Main properties Copy Section

For details, please refer to the distribution/conf/plain_acl.yml configuration file.

3. Cluster deployment with permission control Copy Chapter

After defining the permission attribute in the distribution/conf/plain_acl.yml configuration file as described above, open the aclEnable switch variable to enable the ACL feature of the RocketMQ cluster.The configuration file of the ACL feature enabled on the broker is as follows:

brokerClusterName=DefaultCluster
brokerName=broker-a
brokerId=0
deleteWhen=04
fileReservedTime=48
brokerRole=ASYNC_MASTER
flushDiskType=ASYNC_FLUSH
storePathRootDir=/data/rocketmq/rootdir-a-m
storePathCommitLog=/data/rocketmq/commitlog-a-m
autoCreateSubscriptionGroup=true
## if acl is open,the flag will be true
aclEnable=true
listenPort=10911
brokerIP1=XX.XX.XX.XX1
namesrvAddr=XX.XX.XX.XX:9876

4. Main process of access control Copy Chapter

The main ACL process is divided into two parts, including privilege resolution and privilege check.

4.1 Privilege resolution Copy Section

The Broker side parses the client's RequestCommand request and obtains the attribute field that needs to be authenticated.
main attributes:
(1) AccessKey:Similar to the user name, on behalf of the user entity, the permission data corresponds to it;
(2) Signature:The client obtains the string according to the signature of the SecretKey, and the server uses the SecretKey to perform signature verification.

4.2 Privilege check Copy Section

The check logic of the right side of the broker is mainly divided into the following steps:
(1) Check if the global IP whitelist is hit; if yes, the check passes; otherwise, go to step (2);
(2) Check if the user IP whitelist is hit; if yes, the check passes; otherwise, go to step (3);
(3) Check the signature, if the verification fails, throw an exception; if the verification passes, go to step (4);
(4) Check the permissions required by the user request and the permissions owned by the user; if not, throw an exception;

The verification of the required permissions of the user requires attention to the following points:
(1) Special requests such as UPDATE_AND_CREATE_TOPIC can only be operated by the admin account;
(2) For a resource, if there is explicit configuration permission, the configured permission is used; if there is no explicit configuration permission, the default permission is adopted;

5. Hot loading modified Access control Copy Chapter

The default implementation of RocketMQ's permission control store is based on the yml configuration file. Users can dynamically modify the properties defined by the permission control without restarting the Broker service node.

File: docs/en/client/java/API_Reference_DefaultMQProducer.md Copy Chapter

DefaultMQProducer Copy Chapter

Class introduction Copy Section

public class DefaultMQProducer extends ClientConfig implements MQProducer

DefaultMQProducer is the entry point for an application to post messages. Out of the box, you can quickly create a producer with a no-argument constructor. It is mainly responsible for message sending and supports synchronous, asynchronous, and one-way sends. All of these send methods support batch sends. The parameters of the sender can be adjusted through the getter/setter methods provided by this class. DefaultMQProducer has multiple send methods, and each method is slightly different. Make sure you know the usage before you use it. Below is a producer example. See more examples.

public class Producer {
    public static void main(String[] args) throws MQClientException {
        // create a producer with producer_group_name
        DefaultMQProducer producer = new DefaultMQProducer("ProducerGroupName");

        // start the producer
        producer.start();

        for (int i = 0; i < 128; i++)
            try {
            	// construct the msg
                Message msg = new Message("TopicTest",
                        "TagA",
                        "OrderID188",
                        "Hello world".getBytes(RemotingHelper.DEFAULT_CHARSET));

                // send sync
                SendResult sendResult = producer.send(msg);

                // print the result
                System.out.printf("%s%n", sendResult);
            } catch (Exception e) {
                e.printStackTrace();
            }

        producer.shutdown();
    }
}

Note : This class is thread safe. It can be safely shared between multiple threads after configuration and startup is complete.

Variable Copy Section

construction method Copy Section

File: docs/en/dledger/deploy_guide.md Copy Chapter

Dledger cluster deployment

preface Copy Chapter

This document introduces how to deploy auto failover RocketMQ-on-DLedger Group.

RocketMQ-on-DLedger Group is a broker group with same name, needs at least 3 nodes, elect a Leader by Raft algorithm automatically, the others as Follower, replicating data between Leader and Follower for system high available.
RocketMQ-on-DLedger Group can failover automatically, and maintains consistent.
RocketMQ-on-DLedger Group can scale up horizontal, that is, can deploy any RocketMQ-on-DLedger Groups providing services external.

1. New cluster deployment Copy Chapter

1.1 Write the configuration

each RocketMQ-on-DLedger Group needs at least 3 machines.(assuming 3 in this document)
write 3 configuration files, advising refer to the directory of conf/dledger 's example configuration file.
key configuration items:

the following presents an example configuration conf/dledger/broker-n0.conf.

brokerClusterName = RaftCluster
brokerName=RaftNode00
listenPort=30911
namesrvAddr=127.0.0.1:9876
storePathRootDir=/tmp/rmqstore/node00
storePathCommitLog=/tmp/rmqstore/node00/commitlog
enableDLegerCommitLog=true
dLegerGroup=RaftNode00
dLegerPeers=n0-127.0.0.1:40911;n1-127.0.0.1:40912;n2-127.0.0.1:40913
## must be unique
dLegerSelfId=n0
sendMessageThreadPoolNums=16

1.2 Start Broker Copy Section

Startup stays consistent with the old version.

nohup sh bin/mqbroker -c conf/dledger/xxx-n0.conf &
nohup sh bin/mqbroker -c conf/dledger/xxx-n1.conf &
nohup sh bin/mqbroker -c conf/dledger/xxx-n2.conf &

2. Upgrade old cluster Copy Chapter

If old cluster deployed in Master mode, then each Master needs to be transformed into a RocketMQ-on-DLedger Group.
If old cluster deployed in Master-Slave mode, then each Master-Slave group needs to be transformed into a RocketMQ-on-DLedger Group.

2.1 Kill old Broker Copy Section

execute kill command, or call bin/mqshutdown broker.

2.2 Check old Commitlog Copy Section

Each node in RocketMQ-on-DLedger group is compatible with old Commitlog, but Raft replicating process works on the adding message only. So, to avoid occurring exceptions, old Commitlog must be consistent.
If old cluster deployed in Master-Slave mode, it maybe inconsistent after shutdown. Advising use md5sum to check at least 2 recently Commitlog file, if occur inconsistent, maintain consistent by copy.

Although RocketMQ-on-DLedger Group can deployed with 2 nodes, it lacks failover ability(at least 3 nodes can tolerate one node fail).
Make sure that both Master and Slave's Commitlog is consistent, then prepare 3 machines, copy old Commitlog from Master to this 3 machines(BTW, copy the config directory).

Then, go ahead to set configurations.

2.3 Modify configuration Copy Section

Refer to New cluster deployment.

2.4 Restart Broker Copy Section

Refer to New cluster deployment.

File: docs/en/dledger/quick_start.md Copy Chapter

Dledger Quick Deployment

preface Copy Section

This document is mainly introduced for how to build and deploy auto failover RocketMQ cluster based on DLedger.

For detailed new cluster deployment and old cluster upgrade document, please refer to Deployment Guide.

1. Build from source code Copy Section

Build phase contains two parts, first, build DLedger, then build RocketMQ.

1.1 Build DLedger

$ git clone https://github.com/openmessaging/dledger.git
$ cd dledger
$ mvn clean install -DskipTests

1.2 Build RocketMQ

$ git clone https://github.com/apache/rocketmq.git
$ cd rocketmq
$ git checkout -b store_with_dledger origin/store_with_dledger
$ mvn -Prelease-all -DskipTests clean install -U

2. Quick Deployment Copy Section

after build successful

#{rocketmq-version} replace with rocketmq actual version. example: 5.0.0-SNAPSHOT
$ cd distribution/target/rocketmq-{rocketmq-version}/rocketmq-{rocketmq-version}
$ sh bin/dledger/fast-try.sh start

if the above commands executed successfully, then check cluster status by using mqadmin operation commands.

$ sh bin/mqadmin clusterList -n 127.0.0.1:9876

If everything goes well, the following content will appear:

（BID is 0 indicate Master, the others are Follower）

After startup successful, producer can produce message, and then test failover scenario.

Stop cluster fastly, execute the following command:

$ sh bin/dledger/fast-try.sh stop

Quick deployment, default configuration is in directory conf/dledger, default storage path is /tmp/rmqstore.

3. Failover Copy Section

After successful deployment, kill Leader process(as the above example, kill process that binds port 30931), about 10 seconds elapses, use clusterList command check cluster's status, Leader switch to another node.

File: docs/en/msg_trace/user_guide.md Copy Chapter

message trace

1. Message trace data's key properties Copy Chapter

2. Enable message trace in cluster deployment Copy Chapter

2.1 Broker's configuration file Copy Section

following by Broker's properties file configuration that enable message trace:

brokerClusterName=DefaultCluster
brokerName=broker-a
brokerId=0
deleteWhen=04
fileReservedTime=48
brokerRole=ASYNC_MASTER
flushDiskType=ASYNC_FLUSH
storePathRootDir=/data/rocketmq/rootdir-a-m
storePathCommitLog=/data/rocketmq/commitlog-a-m
autoCreateSubscriptionGroup=true
## if msg tracing is open,the flag will be true
traceTopicEnable=true
listenPort=10911
brokerIP1=XX.XX.XX.XX1
namesrvAddr=XX.XX.XX.XX:9876

2.2 Common mode Copy Section

Each Broker node in RocketMQ cluster used for storing message trace data that client collected and sent. So, there is no requirements and limitations to the size of Broker node in RocketMQ cluster.

2.3 IO physical isolation mode Copy Section

For huge amounts of message trace data scenario, we can select any one Broker node in RocketMQ cluster used for storing message trace data special, thus, common message data's IO are isolated from message trace data's IO in physical, not impact each other. In this mode, RocketMQ cluster must have at least two Broker nodes, the one that defined as storing message trace data.

2.4 Start Broker that enable message trace Copy Section

nohup sh mqbroker -c ../conf/2m-noslave/broker-a.properties &

3. Save the definition of topic that with support message trace Copy Chapter

RocketMQ's message trace feature supports two types of storage.

3.1 System level TraceTopic Copy Section

Be default, message trace data is stored in system level TraceTopic(topic name: RMQ_SYS_TRACE_TOPIC). That topic will be created at startup of broker(As mentioned above, set traceTopicEnable to true in Broker's configuration).

3.2 User defined TraceTopic Copy Section

If user don't want to store message trace data in system level TraceTopic, he can create user defined TraceTopic used for storing message trace data(that is, create common topic for storing message trace data). The following part will introduce how client SDK support user defined TraceTopic.

4. Client SDK demo with message trace feature Copy Chapter

For business system adapting to use RocketMQ's message trace feature easily, in design phase, the author add a switch parameter(enableMsgTrace) for enable message trace; add a custom parameter(customizedTraceTopic) for user defined TraceTopic.

4.1 Enable message trace when sending messages Copy Section

DefaultMQProducer producer = new DefaultMQProducer("ProducerGroupName",true,null);
        producer.setNamesrvAddr("XX.XX.XX.XX1");
        producer.start();
            try {
                {
                    Message msg = new Message("TopicTest",
                        "TagA",
                        "OrderID188",
                        "Hello world".getBytes(RemotingHelper.DEFAULT_CHARSET));
                    SendResult sendResult = producer.send(msg);
                    System.out.printf("%s%n", sendResult);
                }

            } catch (Exception e) {
                e.printStackTrace();
            }

4.2 Enable message trace when subscribe messages Copy Section

DefaultMQPushConsumer consumer = new DefaultMQPushConsumer("CID_JODIE_1",true,null);
        consumer.subscribe("TopicTest", "*");
        consumer.setConsumeFromWhere(ConsumeFromWhere.CONSUME_FROM_FIRST_OFFSET);
        consumer.setConsumeTimestamp("20181109221800");
        consumer.registerMessageListener(new MessageListenerConcurrently() {
            @Override
            public ConsumeConcurrentlyStatus consumeMessage(List<MessageExt> msgs, ConsumeConcurrentlyContext context) {
                System.out.printf("%s Receive New Messages: %s %n", Thread.currentThread().getName(), msgs);
                return ConsumeConcurrentlyStatus.CONSUME_SUCCESS;
            }
        });
        consumer.start();
        System.out.printf("Consumer Started.%n");

4.3 Self-defined topic support message trace Copy Section

Adjusting instantiation of DefaultMQProducer and DefaultMQPushConsumer as following code to support user defined TraceTopic.

##Topic_test11111 should be created by user, used for storing message trace data.
        DefaultMQProducer producer = new DefaultMQProducer("ProducerGroupName",true,"Topic_test11111");
        ......

        DefaultMQPushConsumer consumer = new DefaultMQPushConsumer("CID_JODIE_1",true,"Topic_test11111");
        ......

4.4 Send and query message trace by mqadmin command Copy Section

• send message

./mqadmin sendMessage -m true --topic some-topic-name -n 127.0.0.1:9876 -p "your message content"

• query trace

./mqadmin QueryMsgTraceById -n 127.0.0.1:9876 -i "some-message-id"

• query trace result

RocketMQLog:WARN No appenders could be found for logger (io.netty.util.internal.PlatformDependent0).
RocketMQLog:WARN Please initialize the logger system properly.
#Type      #ProducerGroup       #ClientHost          #SendTime            #CostTimes #Status
Pub        1623305799667        xxx.xxx.xxx.xxx       2021-06-10 14:16:40  131ms      success

File: docs/en/proxy/deploy_guide.md Copy Chapter

RocketMQ Proxy Deployment Guide

Overview Copy Chapter

RocketMQ Proxy supports two deployment modes: Local and Cluster.

Configuration Copy Chapter

The configuration file applies to both Cluster and Local mode, whose default path is
distribution/conf/rmq-proxy.json.

`Cluster` Mode Copy Chapter

• Set configuration field nameSrvAddr.
• Set configuration field proxyMode to cluster (case insensitive).

Run the command below.

nohup sh mqproxy &

The command will only launch the Proxy component itself. It assumes that Namesrv nodes are already running at the address specified nameSrvAddr, and broker nodes, registering themselves with nameSrvAddr, are running too.

`Local` Mode Copy Chapter

• Set configuration field nameSrvAddr.
• Set configuration field proxyMode to local (case insensitive).

Run the command below.

nohup sh mqproxy &

The previous command will launch the Proxy, with Broker in the same process. It assumes Namesrv nodes are running at the address specified by nameSrvAddr.

File: docs/en/architecture.md Copy Chapter

Architecture design

Technology Architecture Copy Chapter

The RocketMQ architecture is divided into four parts, as shown in the figure above:

• Producer: The role of message publishing supports distributed cluster mode deployment. Producer selects the corresponding Broker cluster queue for message delivery through MQ's load balancing module. The delivery process supports fast failure and low latency.

• Consumer: The role of message consumption supports distributed cluster deployment. Support push, pull two modes to consume messages. It also supports cluster mode and broadcast mode consumption, and it provides a real-time message subscription mechanism to meet the needs of most users.

• NameServer: NameServer is a very simple Topic routing registry with a role similar to ZooKeeper in Dubbo, which supports dynamic registration and discovery of Broker. It mainly includes two functions: Broker management, NameServer accepts the registration information of the Broker cluster and saves it as the basic data of the routing information. Then provide a heartbeat detection mechanism to check whether the broker is still alive; routing information management, each NameServer will save the entire routing information about the Broker cluster and the queue information for the client query. Then the Producer and Consumer can know the routing information of the entire Broker cluster through the NameServer, so as to deliver and consume the message. The NameServer is usually deployed in a cluster mode, and each instance does not communicate with each other. Broker registers its own routing information with each NameServer, so each NameServer instance stores a complete routing information. When a NameServer is offline for some reason, the Broker can still synchronize its routing information with other NameServers. The Producer and Consumer can still dynamically sense the information of the Broker's routing.

• BrokerServer: Broker is responsible for the storage, delivery and query of messages and high availability guarantees. In order to achieve these functions, Broker includes the following important sub-modules.

1. Remoting Module: The entire broker entity handles requests from the clients side.
2. Client Manager: Topic subscription information for managing the client (Producer/Consumer) and maintaining the Consumer
3. Store Service: Provides a convenient and simple API interface for handling message storage to physical hard disks and query functions.
4. HA Service: Highly available service that provides data synchronization between Master Broker and Slave Broker.
5. Index Service: The message delivered to the Broker is indexed according to a specific Message key to provide a quick query of the message.

Deployment architecture Copy Chapter

RocketMQ Network deployment features Copy Section

• NameServer is an almost stateless node that can be deployed in a cluster without any information synchronization between nodes.

• The broker deployment is relatively complex. The Broker is divided into the Master and the Slave. One Master can correspond to multiple Slaves. However, one Slave can only correspond to one Master. The correspondence between the Master and the Slave is defined by specifying the same BrokerName and different BrokerId. The BrokerId 0 indicates Master, non-zero means Slave. The Master can also deploy multiple. Each broker establishes a long connection with all nodes in the NameServer cluster, and periodically registers Topic information to all NameServers. Note: The current RocketMQ version supports a Master Multi Slave on the deployment architecture, but only the slave server with BrokerId=1 will participate in the read load of the message.

• The Producer establishes a long connection with one of the nodes in the NameServer cluster (randomly selected), periodically obtains Topic routing information from the NameServer, and establishes a long connection to the Master that provides the Topic service, and periodically sends a heartbeat to the Master. Producer is completely stateless and can be deployed in a cluster.

• The Consumer establishes a long connection with one of the nodes in the NameServer cluster (randomly selected), periodically obtains Topic routing information from the NameServer, and establishes a long connection to the Master and Slave that provides the Topic service, and periodically sends heartbeats to the Master and Slave. The Consumer can subscribe to the message from the Master or subscribe to the message from the Slave. When the consumer pulls the message to the Master, the Master server will generate a read according to the distance between the offset and the maximum offset. I/O), and whether the server is readable or not, the next time it is recommended to pull from the Master or Slave.

Describe the cluster workflow in conjunction with the deployment architecture diagram:

• Start the NameServer, listen to the port after the NameServer, and wait for the Broker, Producer, and Consumer to connect, which is equivalent to a routing control center.
• The Broker starts, keeps a long connection with all NameServers, and sends heartbeat packets periodically. The heartbeat packet contains the current broker information (IP+ port, etc.) and stores all Topic information. After the registration is successful, there is a mapping relationship between Topic and Broker in the NameServer cluster.
• Before sending and receiving a message, create a Topic. When creating a Topic, you need to specify which Brokers the Topic should be stored on, or you can automatically create a Topic when sending a message.
• Producer sends a message. When starting, it first establishes a long connection with one of the NameServer clusters, and obtains from the NameServer which Brokers are currently sent by the Topic. Polling selects a queue from the queue list and then establishes with the broker where the queue is located. Long connection to send a message to the broker.
• The Consumer is similar to the Producer. It establishes a long connection with one of the NameServers, obtains which Brokers the current Topic exists on, and then directly establishes a connection channel with the Broker to start consuming messages.

File: docs/en/best_practice.md Copy Chapter

Best practices

1 Producer Copy Chapter

1.1 Attention of send message Copy Section

1 Uses of tags

An application should use one topic as far as possible, but identify the message's subtype with tags.Tags can be set freely by the application.
Only when producers set tags while sending messages, can consumers to filter messages through broker with tags when subscribing messages: message.setTags("TagA").

2 Uses of keys

The unique identifier for each message at the business level set to the Keys field to help locate message loss problems in the future.
The server creates an index(hash index) for each message, and the application can query the message content via Topic,key,and who consumed the message.
Since it is a hash index, make sure that the key is as unique as possible to avoid potential hash conflicts.

// order id 
   String orderId = "20034568923546";   
   message.setKeys(orderId);

If you have multiple keys for a message, please concatenate them with 'KEY_SEPARATOR' char, as shown below:

// order id 
   String orderId = "20034568923546";
   String otherKey = "19101121210831";
   String keys = new StringBuilder(orderId)
           .append(org.apache.rocketmq.common.message.MessageConst.KEY_SEPARATOR)
           .append(otherKey).toString();
   message.setKeys(keys);

And if you want to query the message, please use orderId and otherKey to query respectively instead of keys,
because the server will unwrap keys with KEY_SEPARATOR and create corresponding index.
In the above example, the server will create two indexes, one for orderId and one for otherKey.

3 Log print

Print the message log when send success or failed, make sure to print the SendResult and key fields.
Send messages is successful as long as it does not throw exception. Send successful will have multiple states defined in sendResult.
Each state is describing below:

• SEND_OK

Message send successfully.Note that even though message send successfully, but it doesn't mean than it is reliable.
To make sure nothing lost, you should also enable the SYNC_MASTER or SYNC_FLUSH.

• FLUSH_DISK_TIMEOUT

Message send successfully, but the server flush messages to disk timeout.At this point, the message has entered the server's memory, and the message will be lost only when the server is down.
Flush mode and sync flush time interval can be set in the configuration parameters. It will return FLUSH_DISK_TIMEOUT when Broker server doesn't finish flush message to disk in timeout(default is 5s
) when sets FlushDiskType=SYNC_FLUSH(default is async flush).

• FLUSH_SLAVE_TIMEOUT

Message send successfully, but sync to slave timeout.At this point, the message has entered the server's memory, and the message will be lost only when the server is down.
It will return FLUSH_SLAVE_TIMEOUT when Broker server role is SYNC_MASTER(default is ASYNC_MASTER),and it doesn't sync message to slave successfully in the timeout(default 5s).

• SLAVE_NOT_AVAILABLE

Message send successfully, but slave is not available.It will return SLAVE_NOT_AVAILABLE when Broker role is SYNC_MASTER(default is ASYNC_MASTER), and it doesn't have a slave server available.

1.2 Handling of message send failure Copy Section

Send method of producer itself supports internal retry. The logic of retry is as follows:

• At most twice.
• Try next broker when sync send mode, try current broker when async mode. The total elapsed time of this method does not exceed the value of sendMsgTimeout(default is 10s).
• It will not be retried when the message is sent to the Broker with a timeout exception.

The strategy above ensures the success of message sending to some extent.If the business has a high requirement for message reliability, it is recommended to add the corresponding retry logic:
for example, if the sync send method fails, try to store the message in DB, and then retry periodically by the bg thread to ensure the message must send to broker successfully.

Why the above DB retry strategy is not integrated into the MQ client, but requires the application to complete it by itself is mainly based on the following considerations:
First, the MQ client is designed to be stateless mode, convenient for arbitrary horizontal expansion, and only consumes CPU, memory and network resources.
Second, if the MQ client internal integration a KV storage module, the data can only be relatively reliable when sync flush to disk, but the sync flush will cause performance lose, so it's usually
use async flush.Because the application shutdown is not controlled by the MQ operators, A violent shutdown like kill -9 may often occur, resulting in data not flushed to disk and being lost.
Thirdly, the producer is a virtual machine with low reliability, which is not suitable for storing important data.
In conclusion, it is recommended that the retry process must be controlled by the application.

1.3 Send message by oneway Copy Section

Typically, this is the process by which messages are sent:

• Client send request to server
• Server process request
• Server response to client
  So, the time taken to send a message is the sum of the three steps above.Some scenarios require very little time, but not much reliability, such as log collect application.
  This type application can use oneway to send messages. Oneway only send request without waiting for a reply, and send a request at the client implementation level is simply the overhead of an
  operating system call that writes data to the client's socket buffer, this process that typically takes microseconds.

2 Consumer Copy Chapter

3 Broker Copy Chapter

3.1 Broker Role Copy Section

3.2 FlushDiskType Copy Section

3.3 Broker Configuration Copy Section

2. Official Technical Reference & Guides (apache/rocketmq-site) Copy Chapter

Introduction

This project is the new official documentation site for rocketmq.
This website is built using Docusaurus 2, a modern static website generator.

For all of you who contribute documents, here are a few things to keep in mind：

1. For the person responsible for writing the documentation, the only thing you need to modify is the content under ‘/docs’. Find the document you are responsible for under ‘/docs’ and write it in markdown. The rest of the site is automatic, so please do not modify it.

2. For those who do translations, we are currently placing English documents at ‘/docs/09-English’ for the time being due to the error-prone nature of the multilingual version of the site.

3. The framework we currently use supports some nice markdown features, please refer to it and try to speak about the beautiful writing of the document.Markdown Features

For those of you who have contributed documentation and wish to see the results after writing, please refer to the following command.

Local Development Copy Section

$ npm install
$ npm start

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.