Skip to content

Commit dee5109

Browse files
DivyanshIITBDivyanshIITB
authored
[ISSUE #8243] Update Configuration Docs for RocketMQ 5.x Compatibility (#9258)
1 parent 27c2916 commit dee5109

File tree

2 files changed

+87
-113
lines changed

2 files changed

+87
-113
lines changed

‎docs/en/Configuration_Client.md

+68-80
Original file line numberDiff line numberDiff line change
@@ -1,119 +1,107 @@
11
## Client Configuration
22

3-
Relative to RocketMQ's Broker cluster, producers and consumers are client. In this section, it mainly describes the common behavior configuration of producers and consumers.
4-
​
5-
### 1 Client Addressing mode
3+
Relative to RocketMQ's Broker cluster, producers and consumers are clients. This section describes the common behavior configuration of producers and consumers, including updates for **RocketMQ 5.x**.
64

7-
```RocketMQ``` can let client find the ```Name Server```, and then find the ```Broker```by the ```Name Server```. Followings show a variety of configurations, and priority level from highly to lower, the highly priority configurations can override the lower priority configurations.
5+
### 1 Client Addressing Mode
86

9-
- Specified ```Name Server``` address in the code, and multiple ```Name Server``` addresses are separated by semicolons
7+
`RocketMQ` allows clients to locate the `Name Server`, which then helps them find the `Broker`. Below are various configurations, prioritized from highest to lowest. Higher priority configurations override lower ones.
8+
9+
- Specified `Name Server` address in the code (multiple addresses separated by semicolons):
1010

1111
```java
1212
producer.setNamesrvAddr("192.168.0.1:9876;192.168.0.2:9876");
13-
1413
consumer.setNamesrvAddr("192.168.0.1:9876;192.168.0.2:9876");
1514
```
16-
- Specified ```Name Server``` address in the Java setup parameters
15+
16+
- Specified `Name Server` address in Java setup parameters:
1717

1818
```text
1919
-Drocketmq.namesrv.addr=192.168.0.1:9876;192.168.0.2:9876
2020
```
21-
- Specified ```Name Server``` address in the environment variables
21+
22+
- Specified `Name Server` address in environment variables:
2223

2324
```text
24-
export NAMESRV_ADDR=192.168.0.1:9876;192.168.0.2:9876
25+
export NAMESRV_ADDR=192.168.0.1:9876;192.168.0.2:9876
2526
```
26-
- HTTP static server addressing(default)
2727

28-
After client started, it will access the http static server address, as: <http://jmenv.tbsite.net:8080/rocketmq/nsaddr>, this URL return the following contents:
28+
- HTTP static server addressing (default):
2929

30+
Clients retrieve `Name Server` addresses from a static HTTP server:
3031
```text
31-
192.168.0.1:9876;192.168.0.2:9876
32+
http://jmenv.tbsite.net:8080/rocketmq/nsaddr
3233
```
33-
By default, the client accesses the HTTP server every 2 minutes, and update the local Name Server address.The URL is hardcoded in the code, you can change the target server by updating ```/etc/hosts``` file, such as add following configuration at the ```/etc/hosts```:
34-
```text
35-
10.232.22.67 jmenv.tbsite.net
36-
```
37-
HTTP static server addressing is recommended, because it is simple client deployment, and the Name Server cluster can be upgraded hot.
34+
35+
- **New in RocketMQ 5.x:**
36+
- Improved service discovery mechanism, allowing dynamic Name Server registration.
37+
- Introduces `VIP_CHANNEL_ENABLED` for better failover:
38+
39+
```java
40+
producer.setVipChannelEnabled(false);
41+
consumer.setVipChannelEnabled(false);
42+
```
3843

3944
### 2 Client Configuration
4045

41-
```DefaultMQProducer```,```TransactionMQProducer```,```DefaultMQPushConsumer```,```DefaultMQPullConsumer``` all extends the ```ClientConfig``` Class, ```ClientConfig``` as the client common configuration class. Client configuration style like getXXX,setXXX, each of the parameters can config by spring and also config their in the code. Such as the ```namesrvAddr``` parameter: ```producer.setNamesrvAddr("192.168.0.1:9876")```, same with the other parameters.
46+
`DefaultMQProducer`, `TransactionMQProducer`, `DefaultMQPushConsumer`, and `DefaultMQPullConsumer` all extend the `ClientConfig` class, which provides common client configurations.
4247

4348
#### 2.1 Client Common Configuration
4449

45-
| Parameter Name | Default Value | Description |
46-
| ----------------------------- | ------- | ------------------------------------------------------------ |
47-
| namesrvAddr | | Name Server address list, multiple NameServer addresses are separated by semicolons |
48-
| clientIP | local IP | Client local ip address, some machines will fail to recognize the client IP address, which needs to be enforced in the code |
49-
| instanceName | DEFAULT | Name of the client instance, Multiple producers and consumers created by the client actually share one internal instance (this instance contains network connection, thread resources, etc.). |
50-
| clientCallbackExecutorThreads | 4 | Number of communication layer asynchronous callback threads |
51-
| pollNameServerInterval | 30000 | Polling the Name Server interval in milliseconds |
52-
| heartbeatBrokerInterval | 30000 | The heartbeat interval, in milliseconds, is sent to the Broker |
53-
| persistConsumerOffsetInterval | 5000 | The persistent Consumer consumes the progress interval in milliseconds |
50+
| Parameter Name | Default Value | Description |
51+
|-------------------------------|---------------|--------------|
52+
| namesrvAddr | | Name Server address list (semicolon-separated) |
53+
| clientIP | Local IP | Client's local IP address (useful if automatic detection fails) |
54+
| instanceName | DEFAULT | Unique name for the client instance |
55+
| clientCallbackExecutorThreads | 4 | Number of communication layer asynchronous callback threads |
56+
| pollNameServerInterval | 30000 | Interval (ms) to poll Name Server |
57+
| heartbeatBrokerInterval | 30000 | Interval (ms) for sending heartbeats to Broker |
58+
| persistConsumerOffsetInterval | 5000 | Interval (ms) for persisting consumer offsets |
59+
| **autoUpdateNameServer** (5.x) | true | Automatically update Name Server addresses from registry |
60+
| **instanceId** (5.x) | | Unique identifier for each client instance |
5461

5562
#### 2.2 Producer Configuration
5663

57-
| Parameter Name | Default Value | Description |
58-
| -------------------------------- | ---------------- | ------------------------------------------------------------ |
59-
| producerGroup | DEFAULT_PRODUCER | The name of the Producer group. If multiple producers belong to one application and send the same message, they should be grouped into the same group |
60-
| createTopicKey | TBW102 | When a message is sent, topics that do not exist on the server are automatically created and a Key is specified that can be used to configure the default route to the topic where the message is sent.|
61-
| defaultTopicQueueNums | 4 | The number of default queue when sending messages and auto created topic which not exists the server|
62-
| sendMsgTimeout | 3000 | Timeout time of sending message in milliseconds |
63-
| compressMsgBodyOverHowmuch | 4096 | The message Body begins to compress beyond the size(the Consumer gets the message automatically unzipped.), unit of byte|
64-
| retryAnotherBrokerWhenNotStoreOK | FALSE | If send message and return sendResult but sendStatus!=SEND_OK, Whether to resend |
65-
| retryTimesWhenSendFailed | 2 | If send message failed, maximum number of retries, this parameter only works for synchronous send mode|
66-
| maxMessageSize | 4MB | Client limit message body size, over it may error. Server also limit so need to work with server |
67-
| transactionCheckListener | | The transaction message looks back to the listener, if you want send transaction message, you must setup this
68-
| checkThreadPoolMinSize | 1 | Minimum of thread in thread pool when Broker look back Producer transaction status |
69-
| checkThreadPoolMaxSize | 1 | Maximum of thread in thread pool when Broker look back Producer transaction status |
70-
| checkRequestHoldMax | 2000 | Producer local buffer request queue size when Broker look back Producer transaction status |
71-
| RPCHook | null | This parameter is passed in when the Producer is creating, including the pre-processing before the message sending and the processing after the message response. The user can do some security control or other operations in the first interface.|
64+
| Parameter Name | Default Value | Description |
65+
|--------------------------------|----------------------|--------------|
66+
| producerGroup | DEFAULT_PRODUCER | Producer group name |
67+
| sendMsgTimeout | 3000 | Timeout (ms) for sending messages |
68+
| retryTimesWhenSendFailed | 2 | Max retries for failed messages |
69+
| **enableBatchSend** (5.x) | true | Enables batch message sending |
70+
| **enableBackPressure** (5.x) | true | Prevents overload in high-traffic scenarios |
7271

7372
#### 2.3 PushConsumer Configuration
7473

75-
| Parameter Name | Default Value | Description |
76-
| ---------------------------- | ----------------------------- | ------------------------------------------------------------ |
77-
| consumerGroup | DEFAULT_CONSUMER | Consumer group name. If multi Consumer belong to an application, subscribe the same message and consume logic as the same, they should be gathered together |
78-
| messageModel | CLUSTERING | Message support two mode: cluster consumption and broadcast consumption |
79-
| consumeFromWhere | CONSUME_FROM_LAST_OFFSET | After Consumer started, default consumption from last location, it include two situation: One is last consumption location is not expired, and consumption start at last location; The other is last location expired, start consumption at current queue's first message |
80-
| consumeTimestamp | Half an hour ago | Only consumeFromWhere=CONSUME_FROM_TIMESTAMP, this can work |
81-
| allocateMessageQueueStrategy | AllocateMessageQueueAveragely | Implements strategy of Rebalance algorithms |
82-
| subscription | | subscription relation |
83-
| messageListener | | message listener |
84-
| offsetStore | | Consumption progress store |
85-
| consumeThreadMin | 20 | Minimum of thread in consumption thread pool |
86-
| consumeThreadMax | 20 | Maximum of thread in consumption thread pool |
87-
| | | |
88-
| consumeConcurrentlyMaxSpan | 2000 | Maximum span allowed for single queue parallel consumption |
89-
| pullThresholdForQueue | 1000 | Pull message local queue cache maximum number of messages |
90-
| pullInterval | 0 | Pull message interval, because long polling it is 0, but for flow control, you can set value which greater than 0 in milliseconds |
91-
| consumeMessageBatchMaxSize | 1 | Batch consume message |
92-
| pullBatchSize | 32 | Batch pull message |
74+
| Parameter Name | Default Value | Description |
75+
|--------------------------------------|------------------------------------|-------------|
76+
| consumerGroup | DEFAULT_CONSUMER | Consumer group name |
77+
| messageModel | CLUSTERING | Message consumption mode (CLUSTERING or BROADCAST) |
78+
| consumeFromWhere | CONSUME_FROM_LAST_OFFSET | Default consumption position |
79+
| consumeThreadMin | 20 | Min consumption thread count |
80+
| consumeThreadMax | 20 | Max consumption thread count |
81+
| **Rebalance Strategies (5.x)** | AllocateMessageQueueAveragelyByCircle | New rebalance strategy for better distribution |
9382

9483
#### 2.4 PullConsumer Configuration
9584

96-
| Parameter Name | Default Value | Description |
97-
| -------------------------------- | ----------------------------- | ------------------------------------------------------------ |
98-
| consumerGroup | DEFAULT_CONSUMER | Consumer group name. If multi Consumer belong to an application, subscribe the same message and consume logic as the same, they should be gathered together |
99-
| brokerSuspendMaxTimeMillis | 20000 | Long polling, Consumer pull message request suspended for the longest time in the Broker in milliseconds |
100-
| consumerTimeoutMillisWhenSuspend | 30000 | Long polling, Consumer pull message request suspend in the Broker over this time value, client think timeout. Unit is milliseconds |
101-
| consumerPullTimeoutMillis | 10000 | Not long polling, timeout time of pull message in milliseconds |
102-
| messageModel | CLUSTERING | Message support two mode: cluster consumption and broadcast consumption |
103-
| messageQueueListener | | Listening changing of queue |
104-
| offsetStore | | Consumption schedule store |
105-
| registerTopics | | Collection of registered topics |
106-
| allocateMessageQueueStrategy | AllocateMessageQueueAveragely | Implements strategy about Rebalance algorithm |
85+
| Parameter Name | Default Value | Description |
86+
|------------------------------------|------------------------------|-------------|
87+
| consumerGroup | DEFAULT_CONSUMER | Consumer group name |
88+
| brokerSuspendMaxTimeMillis | 20000 | Max suspension time (ms) for long polling |
89+
| consumerPullTimeoutMillis | 10000 | Timeout (ms) for pull requests |
90+
| **messageGroup** (5.x) | | Enables orderly consumption based on groups |
10791

10892
#### 2.5 Message Data Structure
10993

110-
| Field Name | Default Value | Description |
111-
| -------------- | ------ | ------------------------------------------------------------ |
112-
| Topic | null | Required, the name of the topic to which the message belongs |
113-
| Body | null | Required, message body |
114-
| Tags | null | Optional, message tag, convenient for server filtering. Currently only one tag per message is supported |
115-
| Keys | null | Optional, represent this message's business keys, server create hash indexes based keys. After setting, you can find message by ```Topics```,```Keys``` in Console system. Because of hash indexes, please make key as unique as possible, such as order number, goods Id and so on.|
116-
| Flag | 0 | Optional, it is entirely up to the application, and RocketMQ does not intervene |
117-
| DelayTimeLevel | 0 | Optional, message delay level, 0 represent no delay, greater tan 0 can consume |
118-
| WaitStoreMsgOK | TRUE | Optional, indicates whether the message is not answered until the server is down. |
94+
| Field Name | Default Value | Description |
95+
|-------------------|---------------|-------------|
96+
| Topic | null | Required: Name of the message topic |
97+
| Body | null | Required: Message content |
98+
| Tags | null | Optional: Tag for filtering |
99+
| Keys | null | Optional: Business keys (e.g., order IDs) |
100+
| Flag | 0 | Optional: Custom flag |
101+
| DelayTimeLevel | 0 | Optional: Message delay level |
102+
| WaitStoreMsgOK | TRUE | Optional: Acknowledgment before storing |
103+
| **maxReconsumeTimes** (5.x) | | Max retries before moving to dead-letter queue |
104+
| **messageGroup** (5.x) | | Group-based message ordering |
105+
106+
---
119107

0 commit comments

Comments
 (0)