Skip to content

[ISSUE #8243] Update Configuration Docs for RocketMQ 5.x Compatibility #9258

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lizhimins merged 1 commit into from
Mar 20, 2025
Merged

[ISSUE #8243] Update Configuration Docs for RocketMQ 5.x Compatibility #9258

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
148 changes: 68 additions & 80 deletions docs/en/Configuration_Client.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,119 +1,107 @@
## Client Configuration

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.
​
### 1 Client Addressing mode
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**.

```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.
### 1 Client Addressing Mode

- Specified ```Name Server``` address in the code, and multiple ```Name Server``` addresses are separated by semicolons
`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.

- Specified `Name Server` address in the code (multiple addresses separated by semicolons):

```java
producer.setNamesrvAddr("192.168.0.1:9876;192.168.0.2:9876");

consumer.setNamesrvAddr("192.168.0.1:9876;192.168.0.2:9876");
```
- Specified ```Name Server``` address in the Java setup parameters

- Specified `Name Server` address in Java setup parameters:

```text
-Drocketmq.namesrv.addr=192.168.0.1:9876;192.168.0.2:9876
```
- Specified ```Name Server``` address in the environment variables

- Specified `Name Server` address in environment variables:

```text
export NAMESRV_ADDR=192.168.0.1:9876;192.168.0.2:9876
export NAMESRV_ADDR=192.168.0.1:9876;192.168.0.2:9876
```
- HTTP static server addressing(default)

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:
- HTTP static server addressing (default):

Clients retrieve `Name Server` addresses from a static HTTP server:
```text
192.168.0.1:9876;192.168.0.2:9876
http://jmenv.tbsite.net:8080/rocketmq/nsaddr
```
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```:
```text
10.232.22.67 jmenv.tbsite.net
```
HTTP static server addressing is recommended, because it is simple client deployment, and the Name Server cluster can be upgraded hot.

- **New in RocketMQ 5.x:**
- Improved service discovery mechanism, allowing dynamic Name Server registration.
- Introduces `VIP_CHANNEL_ENABLED` for better failover:

```java
producer.setVipChannelEnabled(false);
consumer.setVipChannelEnabled(false);
```

### 2 Client Configuration

```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.
`DefaultMQProducer`, `TransactionMQProducer`, `DefaultMQPushConsumer`, and `DefaultMQPullConsumer` all extend the `ClientConfig` class, which provides common client configurations.

#### 2.1 Client Common Configuration

| Parameter Name | Default Value | Description |
| ----------------------------- | ------- | ------------------------------------------------------------ |
| namesrvAddr | | Name Server address list, multiple NameServer addresses are separated by semicolons |
| 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 |
| 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.). |
| clientCallbackExecutorThreads | 4 | Number of communication layer asynchronous callback threads |
| pollNameServerInterval | 30000 | Polling the Name Server interval in milliseconds |
| heartbeatBrokerInterval | 30000 | The heartbeat interval, in milliseconds, is sent to the Broker |
| persistConsumerOffsetInterval | 5000 | The persistent Consumer consumes the progress interval in milliseconds |
| Parameter Name | Default Value | Description |
|-------------------------------|---------------|--------------|
| namesrvAddr | | Name Server address list (semicolon-separated) |
| clientIP | Local IP | Client's local IP address (useful if automatic detection fails) |
| instanceName | DEFAULT | Unique name for the client instance |
| clientCallbackExecutorThreads | 4 | Number of communication layer asynchronous callback threads |
| pollNameServerInterval | 30000 | Interval (ms) to poll Name Server |
| heartbeatBrokerInterval | 30000 | Interval (ms) for sending heartbeats to Broker |
| persistConsumerOffsetInterval | 5000 | Interval (ms) for persisting consumer offsets |
| **autoUpdateNameServer** (5.x) | true | Automatically update Name Server addresses from registry |
| **instanceId** (5.x) | | Unique identifier for each client instance |

#### 2.2 Producer Configuration

| Parameter Name | Default Value | Description |
| -------------------------------- | ---------------- | ------------------------------------------------------------ |
| 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 |
| 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.|
| defaultTopicQueueNums | 4 | The number of default queue when sending messages and auto created topic which not exists the server|
| sendMsgTimeout | 3000 | Timeout time of sending message in milliseconds |
| compressMsgBodyOverHowmuch | 4096 | The message Body begins to compress beyond the size(the Consumer gets the message automatically unzipped.), unit of byte|
| retryAnotherBrokerWhenNotStoreOK | FALSE | If send message and return sendResult but sendStatus!=SEND_OK, Whether to resend |
| retryTimesWhenSendFailed | 2 | If send message failed, maximum number of retries, this parameter only works for synchronous send mode|
| maxMessageSize | 4MB | Client limit message body size, over it may error. Server also limit so need to work with server |
| transactionCheckListener | | The transaction message looks back to the listener, if you want send transaction message, you must setup this
| checkThreadPoolMinSize | 1 | Minimum of thread in thread pool when Broker look back Producer transaction status |
| checkThreadPoolMaxSize | 1 | Maximum of thread in thread pool when Broker look back Producer transaction status |
| checkRequestHoldMax | 2000 | Producer local buffer request queue size when Broker look back Producer transaction status |
| 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.|
| Parameter Name | Default Value | Description |
|--------------------------------|----------------------|--------------|
| producerGroup | DEFAULT_PRODUCER | Producer group name |
| sendMsgTimeout | 3000 | Timeout (ms) for sending messages |
| retryTimesWhenSendFailed | 2 | Max retries for failed messages |
| **enableBatchSend** (5.x) | true | Enables batch message sending |
| **enableBackPressure** (5.x) | true | Prevents overload in high-traffic scenarios |

#### 2.3 PushConsumer Configuration

| Parameter Name | Default Value | Description |
| ---------------------------- | ----------------------------- | ------------------------------------------------------------ |
| 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 |
| messageModel | CLUSTERING | Message support two mode: cluster consumption and broadcast consumption |
| 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 |
| consumeTimestamp | Half an hour ago | Only consumeFromWhere=CONSUME_FROM_TIMESTAMP, this can work |
| allocateMessageQueueStrategy | AllocateMessageQueueAveragely | Implements strategy of Rebalance algorithms |
| subscription | | subscription relation |
| messageListener | | message listener |
| offsetStore | | Consumption progress store |
| consumeThreadMin | 20 | Minimum of thread in consumption thread pool |
| consumeThreadMax | 20 | Maximum of thread in consumption thread pool |
| | | |
| consumeConcurrentlyMaxSpan | 2000 | Maximum span allowed for single queue parallel consumption |
| pullThresholdForQueue | 1000 | Pull message local queue cache maximum number of messages |
| 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 |
| consumeMessageBatchMaxSize | 1 | Batch consume message |
| pullBatchSize | 32 | Batch pull message |
| Parameter Name | Default Value | Description |
|--------------------------------------|------------------------------------|-------------|
| consumerGroup | DEFAULT_CONSUMER | Consumer group name |
| messageModel | CLUSTERING | Message consumption mode (CLUSTERING or BROADCAST) |
| consumeFromWhere | CONSUME_FROM_LAST_OFFSET | Default consumption position |
| consumeThreadMin | 20 | Min consumption thread count |
| consumeThreadMax | 20 | Max consumption thread count |
| **Rebalance Strategies (5.x)** | AllocateMessageQueueAveragelyByCircle | New rebalance strategy for better distribution |

#### 2.4 PullConsumer Configuration

| Parameter Name | Default Value | Description |
| -------------------------------- | ----------------------------- | ------------------------------------------------------------ |
| 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 |
| brokerSuspendMaxTimeMillis | 20000 | Long polling, Consumer pull message request suspended for the longest time in the Broker in milliseconds |
| consumerTimeoutMillisWhenSuspend | 30000 | Long polling, Consumer pull message request suspend in the Broker over this time value, client think timeout. Unit is milliseconds |
| consumerPullTimeoutMillis | 10000 | Not long polling, timeout time of pull message in milliseconds |
| messageModel | CLUSTERING | Message support two mode: cluster consumption and broadcast consumption |
| messageQueueListener | | Listening changing of queue |
| offsetStore | | Consumption schedule store |
| registerTopics | | Collection of registered topics |
| allocateMessageQueueStrategy | AllocateMessageQueueAveragely | Implements strategy about Rebalance algorithm |
| Parameter Name | Default Value | Description |
|------------------------------------|------------------------------|-------------|
| consumerGroup | DEFAULT_CONSUMER | Consumer group name |
| brokerSuspendMaxTimeMillis | 20000 | Max suspension time (ms) for long polling |
| consumerPullTimeoutMillis | 10000 | Timeout (ms) for pull requests |
| **messageGroup** (5.x) | | Enables orderly consumption based on groups |

#### 2.5 Message Data Structure

| Field Name | Default Value | Description |
| -------------- | ------ | ------------------------------------------------------------ |
| Topic | null | Required, the name of the topic to which the message belongs |
| Body | null | Required, message body |
| Tags | null | Optional, message tag, convenient for server filtering. Currently only one tag per message is supported |
| 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.|
| Flag | 0 | Optional, it is entirely up to the application, and RocketMQ does not intervene |
| DelayTimeLevel | 0 | Optional, message delay level, 0 represent no delay, greater tan 0 can consume |
| WaitStoreMsgOK | TRUE | Optional, indicates whether the message is not answered until the server is down. |
| Field Name | Default Value | Description |
|-------------------|---------------|-------------|
| Topic | null | Required: Name of the message topic |
| Body | null | Required: Message content |
| Tags | null | Optional: Tag for filtering |
| Keys | null | Optional: Business keys (e.g., order IDs) |
| Flag | 0 | Optional: Custom flag |
| DelayTimeLevel | 0 | Optional: Message delay level |
| WaitStoreMsgOK | TRUE | Optional: Acknowledgment before storing |
| **maxReconsumeTimes** (5.x) | | Max retries before moving to dead-letter queue |
| **messageGroup** (5.x) | | Group-based message ordering |

---

Loading
Loading