This is an automated email from the ASF dual-hosted git repository.
liuyu 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 f1e22b92b07 [improve][doc] Add explanations and illustrations for
failover (#514)
f1e22b92b07 is described below
commit f1e22b92b075a74a25ac2caaf04782faf95fe1a6
Author: Anonymitaet <[email protected]>
AuthorDate: Mon Apr 17 08:37:38 2023 +0800
[improve][doc] Add explanations and illustrations for failover (#514)
---
docs/concepts-messaging.md | 60 ++++++++++++++++++++---
static/assets/pulsar-failover-subscriptions-1.svg | 1 +
static/assets/pulsar-failover-subscriptions-2.svg | 1 +
static/assets/pulsar-failover-subscriptions-3.svg | 1 +
static/assets/pulsar-failover-subscriptions-4.svg | 1 +
5 files changed, 58 insertions(+), 6 deletions(-)
diff --git a/docs/concepts-messaging.md b/docs/concepts-messaging.md
index e86923c5a03..def107b0cd5 100644
--- a/docs/concepts-messaging.md
+++ b/docs/concepts-messaging.md
@@ -515,16 +515,64 @@ Exclusive is the default subscription type.
#### Failover
-In the *Failover* type, multiple consumers can attach to the same
subscription. A master consumer is picked for a non-partitioned topic or each
partition of a partitioned topic and receives messages. When the master
consumer disconnects, all (non-acknowledged and subsequent) messages are
delivered to the next consumer in line.
+In the *Failover* type, multiple consumers can attach to the same
subscription.
-* For partitioned topics, the broker will sort consumers by priority level and
lexicographical order of consumer name. The broker will try to evenly assign
partitions to consumers with the highest priority level.
-* For non-partitioned topics, the broker will pick consumers in the order they
subscribe to the non-partitioned topics.
+A master consumer is picked for a non-partitioned topic or each partition of a
partitioned topic and receives messages.
-For example, a partitioned topic has 3 partitions, and 15 consumers. Each
partition will have 1 active consumer and 4 stand-by consumers.
+When the master consumer disconnects, all (non-acknowledged and subsequent)
messages are delivered to the next consumer in line.
-In the diagram below, **Consumer A** is the master consumer while **Consumer
B** would be the next consumer in line to receive messages if **Consumer A** is
disconnected.
+##### Failover | Partitioned topics
-
+For partitioned topics, the broker sorts consumers by priority and
lexicographical order of consumer name.
+
+The broker tries to evenly assign partitions to consumers with the highest
priority.
+
+A consumer is selected by running a module operation `mod (partition index,
consumer index)`.
+
+- If the number of partitions in a partitioned topic is **less** than the
number of consumers:
+
+ For example, in the diagram below, this partitioned topic has 2 partitions
and there are 4 consumers.
+
+ Each partition has 1 active consumer and 1 stand-by consumer.
+
+ - For p0, consumer A is the master consumer, while consumer B would be the
next consumer in line to receive messages if consumer A is disconnected.
+
+ - For p1, consumer C is the master consumer, while consumer D would be the
next consumer in line to receive messages if consumer C is disconnected.
+
+ 
+
+- If the number of partitions in a partitioned topic is **greater** than the
number of consumers:
+
+ For example, in the diagram below, this partitioned topic has 9 partitions
and 3 consumers.
+
+ - p0, p3, and p6 are assigned to consumer A.
+
+ - p1, p4, and p7 are assigned to consumer B.
+
+ - p2, p5, and p8 are assigned to consumer C.
+
+ 
+##### Failover | Non-partitioned topics
+
+- If there is one non-partitioned topic. The broker picks consumers in the
order they subscribe to non-partitioned topics.
+
+ For example, in the diagram below, this non-partitioned topic has 1 topic
and there are 2 consumers.
+
+ The topic has 1 active consumer and 1 stand-by consumer.
+
+ Consumer A is the master consumer, while consumer B would be the next
consumer in line to receive messages if consumer A is disconnected.
+
+ 
+
+- If there are multiple non-partitioned topics, a consumer is selected based
on **consumer name hash** and **topic name hash**. The client uses the same
consumer name to subscribe to all the topics.
+
+ For example, in the diagram below, there are 4 non-partitioned topics and 2
consumers.
+
+ - The non-partitioned topic 1 and non-partitioned topic 4 are assigned to
consumer B.
+
+ - The non-partitioned topic 2 and non-partitioned topic 3 are assigned to
consumer A.
+
+ 
#### Shared
diff --git a/static/assets/pulsar-failover-subscriptions-1.svg
b/static/assets/pulsar-failover-subscriptions-1.svg
new file mode 100644
index 00000000000..e7bf0a53abc
--- /dev/null
+++ b/static/assets/pulsar-failover-subscriptions-1.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg";
xmlns:xlink="http://www.w3.org/1999/xlink"; xmlns:lucid="lucid" width="1020"
height="933.71"><g transform="translate(128.66666666666674 264.18825954861074)"
lucid:page-tab-id="0_0"><path d="M-1806.87-1258.84h3677.74v2581.68h-3677.74z"
fill="#fff"/><path d="M-108.67-244.2h400v893.72h-400z" stroke="#474e55"
stroke-width="2" fill="#edf5ff"/><use xlink:href="#a"
transform="matrix(1,0,0,1,-103.66666666666674,-239.18825954861074)
translate(195 20.83344184 [...]
\ No newline at end of file
diff --git a/static/assets/pulsar-failover-subscriptions-2.svg
b/static/assets/pulsar-failover-subscriptions-2.svg
new file mode 100644
index 00000000000..8ddbae9e811
--- /dev/null
+++ b/static/assets/pulsar-failover-subscriptions-2.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg";
xmlns:xlink="http://www.w3.org/1999/xlink"; xmlns:lucid="lucid" width="938"
height="440"><g transform="translate(1087.356185544226 -201.4498923447768)"
lucid:page-tab-id="0_0"><path d="M-1806.87 0H64v1322.84h-1870.87z"
fill="#fff"/><path d="M-827.36 261.45c33.14 0 60 26.86 60 60s-26.86 60-60
60h-180c-33.13 0-60-26.86-60-60s26.87-60 60-60z" stroke="#474e55"
stroke-width="2" fill="#edf5ff"/><use xlink:href="#a"
transform="matrix(1,0,0,1,-1067.35618554 [...]
\ No newline at end of file
diff --git a/static/assets/pulsar-failover-subscriptions-3.svg
b/static/assets/pulsar-failover-subscriptions-3.svg
new file mode 100644
index 00000000000..d3152ed5834
--- /dev/null
+++ b/static/assets/pulsar-failover-subscriptions-3.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg";
xmlns:xlink="http://www.w3.org/1999/xlink"; xmlns:lucid="lucid" width="940"
height="700"><g transform="translate(26.671561331314138 181.8806440373296)"
lucid:page-tab-id="0_0"><path d="M-1806.87-1258.84h3677.74v2581.68h-3677.74z"
fill="#fff"/><path d="M233.33-161.88c33.14 0 60 26.86 60 60s-26.86 60-60
60h-180c-33.14 0-60-26.86-60-60s26.86-60 60-60z" stroke="#474e55"
stroke-width="2" fill="#edf5ff"/><use xlink:href="#a"
transform="matrix(1,0,0,1,-6.6 [...]
\ No newline at end of file
diff --git a/static/assets/pulsar-failover-subscriptions-4.svg
b/static/assets/pulsar-failover-subscriptions-4.svg
new file mode 100644
index 00000000000..c28b05a7a17
--- /dev/null
+++ b/static/assets/pulsar-failover-subscriptions-4.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg";
xmlns:xlink="http://www.w3.org/1999/xlink"; xmlns:lucid="lucid" width="1020"
height="933.71"><g transform="translate(-49.63018491683454 -431.316975503099)"
lucid:page-tab-id="0_0"><path d="M0 0h1870.87v2581.67H0z" fill="#fff"/><path
d="M69.63 451.32h400v893.7h-400z" stroke="#474e55" stroke-width="2"
fill="#edf5ff"/><use xlink:href="#a"
transform="matrix(1,0,0,1,74.63018491683454,456.316975503099) translate(195
20.83344184027777)"/><use xlink:href="# [...]
\ No newline at end of file
