[fix][doc] Clarify order processing semantics for Key Shared Subscription docs #19063
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
github-actions
bot
added
the
doc
asafm
commented
Dec 26, 2022
| @@ -743,7 +743,7 @@ Consistent Hashing will be used instead of Hash Range for Auto-split if the brok | |||
|
|
|||
| ##### Preserving order of processing | |||
|
|
|||
| Key Shared Subscription type guarantees a key will be processed by a *single* consumer at any given time. When a new consumer a connected, some key will be mapped to it from existing consumers. The broker will not deliver messages to the new consumer until all messages delivered up until connection time will be acknowledged. This will guarantee a certain key is processed by a single consumer at any given time. The trade-off is that if one of the existing consumers is stuck and no time-out was defined (acknowledging for you), the new consumer won't receive any messages until the stuck consumer will resume or gets disconnected. | |||
| Key Shared Subscription type guarantees a key will be processed by a *single* consumer at any given time. When a new consumer is connected, some keys will change their mapping from existing consumers to the new consumer. Once the connection has been established, the broker will record the current read position and associate it with the new consumer. The read position is a marker indicating that messages have been dispatched to the consumers up to this point, and after it, no messages have been dispatched yet. The broker will start delivering messages to the new consumer *only* when all messages up to the read position have been acknowledged. This will guarantee that a certain key is processed by a single consumer at any given time. The trade-off is that if one of the existing consumers is stuck and no time-out was defined (acknowledging for you), the new consumer won't receive any messages until the stuck consumer resumes or gets disconnected. | |||
asafm
commented
Dec 26, 2022
| | Mode | Description | | ||
| |:-----------|-----------| | ||
| | Sync send | The producer waits for an acknowledgment from the broker after sending every message. If the acknowledgment is not received, the producer treats the sending operation as a failure. | | ||
| | Mode | Description | |
asafm
commented
Dec 26, 2022
| 6 | 32 seconds | ||
| 7 | 60 seconds | ||
| 8 | 60 seconds | ||
| | Redelivery count | Redelivery delay | |
asafm
commented
Dec 26, 2022
| 6 | 10 + 32 seconds | ||
| 7 | 10 + 60 seconds | ||
| 8 | 10 + 60 seconds | ||
| | Redelivery count | Redelivery delay | |
asafm
commented
Dec 26, 2022
| `ORIGIN_MESSAGE_ID` | The origin message ID. It is crucial for message tracking. | ||
| `RECONSUMETIMES` | The number of retries to consume messages. | ||
| `DELAY_TIME` | Message retry interval in milliseconds. | ||
| | Special property | Description | |
asafm
commented
Dec 26, 2022
| `tenant` | The topic tenant within the instance. Tenants are essential to multi-tenancy in Pulsar, and spread across clusters. | ||
| `namespace` | The administrative unit of the topic, which acts as a grouping mechanism for related topics. Most topic configuration is performed at the [namespace](#namespaces) level. Each tenant has one or more namespaces. | ||
| `topic` | The final part of the name. Topic names have no special meaning in a Pulsar instance. | ||
| | Topic name component | Description | |
asafm
commented
Dec 26, 2022
| :-----------------|:------------|:------------ | ||
| `Durable` | The cursor is durable, which retains messages and persists the current position. <br />If a broker restarts from a failure, it can recover the cursor from the persistent storage (BookKeeper), so that messages can continue to be consumed from the last consumed position. | `Durable` is the **default** subscription mode. | ||
| `NonDurable` | The cursor is non-durable. <br />Once a broker stops, the cursor is lost and can never be recovered, so that messages **can not** continue to be consumed from the last consumed position. | Reader’s subscription mode is `NonDurable` in nature and it does not prevent data in a topic from being deleted. Reader’s subscription mode **can not** be changed. | ||
| | Subscription mode | Description | Note | |
asafm
commented
Dec 26, 2022
| `RoundRobinPartition` | If no key is provided, the producer will publish messages across all partitions in round-robin fashion to achieve maximum throughput. Please note that round-robin is not done per individual message but rather it's set to the same boundary of batching delay, to ensure batching is effective. While if a key is specified on the message, the partitioned producer will hash the key and assign message to a particular partition. This is the default mode. | ||
| `SinglePartition` | If no key is provided, the producer will randomly pick one single partition and publish all the messages into that partition. While if a key is specified on the message, the partitioned producer will hash the key and assign message to a particular partition. | ||
| `CustomPartition` | Use custom message router implementation that will be called to determine the partition for a particular message. User can create a custom routing mode by using the [Java client](client-libraries-java.md) and implementing the {@inject: javadoc:MessageRouter:/client/org/apache/pulsar/client/api/MessageRouter} interface. | ||
| | Mode | Description | |
asafm
commented
Dec 26, 2022
| :------------------|:------------|:------------ | ||
| Per-key-partition | All the messages with the same key will be in order and be placed in same partition. | Use either `SinglePartition` or `RoundRobinPartition` mode, and Key is provided by each message. | ||
| Per-producer | All the messages from the same producer will be in order. | Use `SinglePartition` mode, and no Key is provided for each message. | ||
| | Ordering guarantee | Description | Routing Mode and Key | |
tisonkun
approved these changes
Dec 26, 2022
momo-jun
approved these changes
Dec 27, 2022
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Modifications
Verifying this change
Does this pull request potentially affect one of the following parts:
If the box was checked, please highlight the changes
Documentation
docdoc-requireddoc-not-neededdoc-complete