[pulsar-site] branch main updated: Docs sync done from apache/pulsar(#c732852)

[ur...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

urfree pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-site.git


The following commit(s) were added to refs/heads/main by this push:
     new 47c7e271304 Docs sync done from apache/pulsar(#c732852)
47c7e271304 is described below

commit 47c7e27130477f7d728b007fd1804ba263cf5130
Author: Pulsar Site Updater <de...@pulsar.apache.org>
AuthorDate: Thu Oct 13 12:01:35 2022 +0000

    Docs sync done from apache/pulsar(#c732852)
---
 site2/website-next/docs/administration-zk-bk.md | 49 +++++++++++++++++--------
 1 file changed, 34 insertions(+), 15 deletions(-)

diff --git a/site2/website-next/docs/administration-zk-bk.md b/site2/website-next/docs/administration-zk-bk.md
index 56555ccb673..03cc889d676 100644
--- a/site2/website-next/docs/administration-zk-bk.md
+++ b/site2/website-next/docs/administration-zk-bk.md
@@ -259,9 +259,9 @@ You can run the following command to check if the bookie you have decommissioned
 
 In Pulsar, you can set *persistence policies* at the namespace level, which determines how BookKeeper handles persistent storage of messages. Policies determine four things:
 
-* The number of acks (guaranteed copies) to wait for each ledger entry.
-* The number of bookies to use for a topic.
-* The number of writes to make for each ledger entry.
+* Ensemble (E) size, Number of [bookies](reference-terminology.md#bookie) to use for storing entries in a ledger.
+* Write quorum (Q<sub>w</sub>) size, Replication factor for storing entries (messages) in a ledger.
+* Ack quorum (Q<sub>a</sub>) size, Number of guaranteed copies (acks to wait for before a write is considered completed).
 * The throttling rate for mark-delete operations.
 
 ### Set persistence policies
@@ -272,21 +272,39 @@ 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:
+
+```shell
+pulsar-admin namespaces set-persistence my-tenant/my-ns -e 3 -w 3 -a 3
 ```
 
+
 #### REST API
 
 {@inject: endpoint|POST|/admin/v2/namespaces/:tenant/:namespace/persistence|operation/setPersistence?version=@pulsar:version_number@}
@@ -294,13 +312,14 @@ pulsar-admin namespaces set-persistence my-tenant/my-ns \
 #### Java
 
 ```java
-// The following must be true: bkEnsemble >= bkQuorum >= bkAckQuorum
+// The following must be true: bkEnsemble >= bkWriteQuorum >= bkAckQuorum
+// Please notice that sticky reads cannot be used unless bkEnsemble == bkWriteQuorum. 
 int bkEnsemble = 3;
-int bkQuorum = 2;
-int bkAckQuorum = 2;
+int bkWriteQuorum = 3;
+int bkAckQuorum = 3;
 double markDeleteRate = 0.7;
 PersistencePolicies policies =
-  new PersistencePolicies(ensemble, quorum, ackQuorum, markDeleteRate);
+  new PersistencePolicies(bkEnsemble, bkWriteQuorum, bkAckQuorum, markDeleteRate);
 admin.namespaces().setPersistence(namespace, policies);
 ```