Anonymitaet commented on code in PR #18003:
URL: https://github.com/apache/pulsar/pull/18003#discussion_r992927006
##########
site2/docs/administration-zk-bk.md:
##########
@@ -272,35 +272,54 @@ You can set persistence policies for BookKeeper at the
[namespace](reference-ter
Use the [`set-persistence`](/tools/pulsar-admin/) subcommand and specify a
namespace as well as any policies that you want to apply. The available flags
are:
-Flag | Description | Default
-:----|:------------|:-------
-`-a`, `--bookkeeper-ack-quorum` | The number of acks (guaranteed copies) to
wait on for each entry | 0
-`-e`, `--bookkeeper-ensemble` | The number of
[bookies](reference-terminology.md#bookie) to use for topics in the namespace | 0
-`-w`, `--bookkeeper-write-quorum` | The number of writes to make for each
entry | 0
-`-r`, `--ml-mark-delete-max-rate` | Throttling rate for mark-delete operations
(0 means no throttle) | 0
+Flag | Description
| Default
+:----|:---------------------------------------------------------------------------------------------------------------------------|:-------
+`-e`, `--bookkeeper-ensemble` | Ensemble (E) size, Number of
[bookies](reference-terminology.md#bookie) to use for storing entries in a
ledger.| 0
+`-w`, `--bookkeeper-write-quorum` | Write quorum (Q<sub>w</sub>) size,
Replication factor for storing entries (messages) in a ledger.
| 0
+`-a`, `--bookkeeper-ack-quorum` | Ack quorum (Q<sub>a</sub>) size, Number of
guaranteed copies (acks to wait for before a write is considered completed)
| 0
+`-r`, `--ml-mark-delete-max-rate` | Throttling rate for mark-delete operations
(0 means no throttle)
| 0
+
+Please notice that sticky reads enabled by `bookkeeperEnableStickyReads=true`
aren’t used unless ensemble size (E) equals write quorum (Q<sub>w</sub>) size.
Sticky reads improve the efficiency of the Bookkeeper read ahead cache when all
reads for a single ledger are sent to a single bookie.
+
+Some rules for choosing the values:
+
+Rule | Description |
+:----|:------------|
+E >= Q<sub>w</sub> >= Q<sub>a</sub>|Ensemble size must be larger or equal than
write quorum size, write quorum size must be larger or equal than ack quorum
size.
+Max bookie failures = Q<sub>a</sub>-1, |This rule must be fulfilled if data
durability is desired in case of bookie failures. To safely tolerate at least
one bookie failure at a time in the ensemble, Q<sub>a</sub> must be set to a
value at least 2.
+E == Q<sub>w</sub> | Sticky reads enabled by
`bookkeeperEnableStickyReads=true` aren't used unless ensemble size (E) equals
write quorum (Q<sub>w</sub>) size.
The following is an example:
```shell
pulsar-admin namespaces set-persistence my-tenant/my-ns \
---bookkeeper-ack-quorum 2 \
---bookkeeper-ensemble 3
+--bookkeeper-ensemble 3 \
+--bookkeeper-write-quorum 3 \
+--bookkeeper-ack-quorum 3
+```
+
+short example:
Review Comment:
```suggestion
Short example:
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
