Format consumer config as table, add remaining fields #495
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
Signed-off-by: Byron Ruth <b@devel.io>
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
Signed-off-by: Byron Ruth <b@devel.io>
Signed-off-by: Byron Ruth <b@devel.io>
gcolliso
reviewed
Sep 26, 2022
nats-concepts/jetstream/consumers.md
Outdated
|
|
||
| The rate of message delivery in both cases is subject to `ReplayPolicy`. A `ReplayInstant` Consumer will receive all messages as fast as possible while a `ReplayOriginal` Consumer will receive messages at the rate they were received, which is great for replaying production traffic in staging. | ||
| In addition to the choice of being push or pull, a consumer can also be **ephemeral** or **durable**. A durable consumer simply by having a *durable name* defined when creating the consumer initially, whereas an ephemeral does not. Durables and ephemeral behave exactly the same except that an ephemeral will be automatically *cleaned up* (deleted) after a period of inactivity, specifically when there are no subscriptions bound to the consumer. By default, durables will remain even when there are periods of inactivity (unless `InactiveThreshold` is set explicitly). |
There was a problem hiding this comment.
Sentence is missing a word "A durable consumer simply by having..."
gcolliso
reviewed
Sep 26, 2022
nats-concepts/jetstream/consumers.md
Outdated
|
|
||
| In the orders example above we have 3 Consumers. The first two select a subset of the messages from the Stream by specifying a specific subject like `ORDERS.processed`. The Stream consumes `ORDERS.*` and this allows you to receive just what you need. The final Consumer receives all messages in a `push` fashion. | ||
| For examples on how to configure consumers with your preferred NATS client, see [NATS by Example](https://natsbyexample.com). |
There was a problem hiding this comment.
If there is a specific example in the NBE, IMO the link should go directly to it so ppl don't have to hunt around.
gcolliso
reviewed
Sep 26, 2022
nats-concepts/jetstream/consumers.md
Outdated
| Consumer names should not contain any of the following characters: ` ` (space), `.`, `*`, `>`, or a path separator (forward or backwards slash) or any non-printable characters. | ||
| | Field | Description | Version | Editable | | ||
| | :--- | :--- | :--- | :--- | | ||
| | Durable | If set, clients can have subscriptions bind to the consumer and _resume_ until the consumer is explicitly deleted. The consumer will durable name cannot contain whitespace, `.`, `*`, `>`, path separators (forward or backwards slash), and non-printable characters. | 2.2.0 | No | |
There was a problem hiding this comment.
"The consumer will durable name..." Should this be 'The consumer with...' ?
gcolliso
reviewed
Sep 26, 2022
nats-concepts/jetstream/consumers.md
Outdated
| - `DeliverLastPerSubject` - When first consuming messages, start with the latest one for each filtered subject currently in the stream. | ||
| - `DeliverNew` - When first consuming messages, the consumer will only start receiving messages that were created after the consumer was created. | ||
| - `DeliverByStartSequence` - When first consuming messages, start at this particular message in the set. The consumer is required to specify `OptStartSeq`, the sequence number to start on. It will receive the closest available message moving forward in the sequence should the message specified have been removed based on the stream limit policy. | ||
| - `DeliverByStartTime` - When first consuming messages, start with messages on or after this time. The consumer is required to specify `OptStartTime`, the time in the stream to start at. It will receive the closest available message on or after that time. |
There was a problem hiding this comment.
I know I'm the grammar police here but can we reword this one "The consumer is required to specify...., the time in the stream to start at." to '....the time at which the stream should start.' ?
gcolliso
reviewed
Sep 26, 2022
| @@ -12,34 +12,36 @@ Streams support various retention policies which define when messages in the str | |||
|
|
|||
| Streams support deduplication using a `Nats-Msg-Id` header and a sliding window within which to track duplicate messages. See the [Message Deduplication](../../using-nats/jetstream/model_deep_dive.md#message-deduplication) section. | |||
|
|
|||
| For examples on how to configure streams with your preferred NATS client, see [NATS by Example](https://natsbyexample.com). | |||
There was a problem hiding this comment.
Same as above, if there is a specific NBE, the link should go there.
Signed-off-by: Byron Ruth <b@devel.io>
|
Thanks @gcolliso. Hopefully addressed all the feedback. |
gcolliso
approved these changes
Sep 26, 2022
jnmoyne
reviewed
Sep 26, 2022
nats-concepts/jetstream/consumers.md
Outdated
| | [MaxAckPending](#maxackpending) | Defines the maximum number of messages, without an acknowledgement, that can be outstanding. Once this limit is reached message delivery will be suspended. This limit applies across _all_ of the consumer's bound subscriptions. A value of -1 means there can be any number of pending acks (i.e. no flow control). This does not apply when the `AckNone` policy is used. | 2.2.0 | Yes | | ||
| | MaxDeliver | The maximum number of times a specific message delivery will be attempted. Applies to any message that is re-sent due to ack policy (i.e. due to a negative ack, or no ack sent by the client). | 2.2.0 | Yes | | ||
| | ReplayPolicy | If the policy is `ReplayOriginal`, the messages in the stream will be pushed to the client at the same rate that they were originally received, simulating the original timing of messages. If the policy is `ReplayInstant` \(the default\), the messages will be pushed to the client as fast as possible while adhering to the Ack Policy, Max Ack Pending and the client's ability to consume those messages. | 2.2.0 | No | | ||
| | Replicas | Sets the number of replicas for the consumer's state. By default, consumers inherit the number of replicas from the stream. | 2.8.3 | Yes | |
There was a problem hiding this comment.
About consumer number of replicas maybe expand to say that the default value 0 means it inherits the number from the stream's
jnmoyne
reviewed
Sep 26, 2022
nats-concepts/jetstream/consumers.md
Outdated
|
|
||
| ### AckAll | ||
| The `MaxAckPending` capability provides one-to-many flow control and applies to both push and pull consumers. For push consumers, `MaxAckPending` is the _only_ form of flow control. However, for pull consumers because the delivery of the messages to the client application is client-driven (hence the 'pull') rather than server initiated (hence the 'push') there is an implicit one-to-one flow control with the subscribers (the maximum batch size of the Fetch calls). Therefore you should remember to set it to an appropriately high value (e.g. the default value of 20000), as it can otherwise place a limit on the horizontal scalability of the processing of the stream in high throughput situations. |
There was a problem hiding this comment.
Default max ack pending value has changed and is now 1000 I believe
jnmoyne
reviewed
Sep 26, 2022
nats-concepts/jetstream/consumers.md
Outdated
| | :--- | :--- | :--- | :--- | | ||
| | DeliverSubject | The subject to deliver messages to. Note, setting this field implicitly decides whether the consumer is push or pull-based. With a deliver subject, the server will _push_ messages to client subscribed to this subject. | 2.2.0 | No | | ||
| | DeliverGroup | The queue group name which, if specified, is then used to distribute the messages between the subscribers to the consumer. This is analogous to a [queue group][queue-group] in core NATS. | 2.2.0 | Yes | | ||
| | FlowControl | Enables per-subscription flow control using a sliding-window protocol. This protocol relies on the server and client exchanging messages to regulate when and how many messages are pushed to the client. This flow control mechanism is in addition to the flow control imposed by `MaxAckPending` across all subscriptions bound to a consumer. | 2.2.0 | Yes | |
There was a problem hiding this comment.
Maybe add 'one-to-one' somewhere to say that this FlowControl setting is for having individual flow control for each client subscribing from the consumer (while max ack pending is 'one-to-many' flow control)?
jnmoyne
reviewed
Sep 26, 2022
nats-concepts/jetstream/consumers.md
Outdated
| | DeliverSubject | The subject to deliver messages to. Note, setting this field implicitly decides whether the consumer is push or pull-based. With a deliver subject, the server will _push_ messages to client subscribed to this subject. | 2.2.0 | No | | ||
| | DeliverGroup | The queue group name which, if specified, is then used to distribute the messages between the subscribers to the consumer. This is analogous to a [queue group][queue-group] in core NATS. | 2.2.0 | Yes | | ||
| | FlowControl | Enables per-subscription flow control using a sliding-window protocol. This protocol relies on the server and client exchanging messages to regulate when and how many messages are pushed to the client. This flow control mechanism is in addition to the flow control imposed by `MaxAckPending` across all subscriptions bound to a consumer. | 2.2.0 | Yes | | ||
| | IdleHeartbeat | If the idle heartbeat period is set, the server will regularly send a status message to the client (i.e. when the period has elapsed) while there are no new messages to send. This lets the client know that the JetStream service is still up and running, even when there is no activity on the stream. The message status header will have a code of 100. Unlike FlowControl, it will have no reply to address. It may have a description like "Idle Heartbeat". | 2.2.0 | Yes | |
There was a problem hiding this comment.
Maybe say that this handling of the heartbeat is done by the client library, doesn't have to be done by the developper?
Signed-off-by: Byron Ruth <b@devel.io>
|
@jnmoyne Addressed the feedback thus far. Thank you! |
|
LGTM |
13 tasks
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.
No description provided.