You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by "zuobiao-zhou (via GitHub)" <gi...@apache.org> on 2023/08/11 05:16:25 UTC
[GitHub] [pulsar-site] zuobiao-zhou opened a new pull request, #674: seo for C&A
zuobiao-zhou opened a new pull request, #674:
URL: https://github.com/apache/pulsar-site/pull/674
This PR do SEO for Concepts and Architecture
<!-- DO NOT REMOVE THIS SECTION. CHECK THE PROPER BOX ONLY. -->
- [x] `doc` <!-- Your PR contains doc changes. Please attach the local preview screenshots (run `./preview.sh` at root path) to your PR description, or else your PR might not get merged. -->
- [ ] `doc-required` <!-- Your PR changes impact docs and you will update later -->
- [ ] `doc-not-needed` <!-- Your PR changes do not impact docs -->
- [ ] `doc-complete` <!-- Docs have been already added -->
--
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: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar-site] Anonymitaet merged pull request #674: [improve][doc] SEO for Concepts and Architecture except Overview and Messaging
Posted by "Anonymitaet (via GitHub)" <gi...@apache.org>.
Anonymitaet merged PR #674:
URL: https://github.com/apache/pulsar-site/pull/674
--
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: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar-site] Anonymitaet commented on pull request #674: seo for C&A
Posted by "Anonymitaet (via GitHub)" <gi...@apache.org>.
Anonymitaet commented on PR #674:
URL: https://github.com/apache/pulsar-site/pull/674#issuecomment-1676525301
Suggest updating the PR title to reflect the actual changes made in this PR.
--
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: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar-site] tisonkun commented on a diff in pull request #674: seo for C&A
Posted by "tisonkun (via GitHub)" <gi...@apache.org>.
tisonkun commented on code in PR #674:
URL: https://github.com/apache/pulsar-site/pull/674#discussion_r1290917024
##########
docs/reference-terminology.md:
##########
@@ -78,18 +67,6 @@ A group of namespaces that have anti-affinity to each other.
A lightweight Pulsar broker in which all components run in a single Java Virtual Machine (JVM) process. Standalone
clusters can be run on a single machine and are useful for development purposes.
-### Cluster
Review Comment:
Any background why we remove these terms?
--
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: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar-site] Anonymitaet commented on a diff in pull request #674: SEO for Concepts and Architecture except Overview and Messaging
Posted by "Anonymitaet (via GitHub)" <gi...@apache.org>.
Anonymitaet commented on code in PR #674:
URL: https://github.com/apache/pulsar-site/pull/674#discussion_r1292900338
##########
docs/reference-terminology.md:
##########
@@ -78,18 +67,6 @@ A group of namespaces that have anti-affinity to each other.
A lightweight Pulsar broker in which all components run in a single Java Virtual Machine (JVM) process. Standalone
clusters can be run on a single machine and are useful for development purposes.
-### Cluster
Review Comment:
I don't think it's necessary to keep those items empty and add links in the reference-terminology.md because we want to navigate users to "concept" topics only on purpose.
--
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: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar-site] zuobiao-zhou commented on a diff in pull request #674: seo for C&A
Posted by "zuobiao-zhou (via GitHub)" <gi...@apache.org>.
zuobiao-zhou commented on code in PR #674:
URL: https://github.com/apache/pulsar-site/pull/674#discussion_r1290943845
##########
docs/reference-terminology.md:
##########
@@ -78,18 +67,6 @@ A group of namespaces that have anti-affinity to each other.
A lightweight Pulsar broker in which all components run in a single Java Virtual Machine (JVM) process. Standalone
clusters can be run on a single machine and are useful for development purposes.
-### Cluster
Review Comment:
As we have included the definitions of certain terms in the Concepts and Architecture chapter, redundant terminology definitions would add to the maintenance complexity. Users can refer to this chapter when seeking the definitions of specific terms.
Perhaps we can place a link at the repeated term's location in "reference-terminology.md" as a substitute for those redundant definitions?
e.g.
## Producer
See [here](https://pulsar.apache.org/docs/next/concepts-clients/#producer).
On the other hand, for instance, when a user searches for "what is Pulsar brokers," we expect the result is https://pulsar.apache.org/docs/next/concepts-architecture-overview instead of https://pulsar.apache.org/docs/next/reference-terminology/. Repetitive definitions would disperse the weight of the expected page.
--
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: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar-site] Anonymitaet commented on a diff in pull request #674: seo for C&A
Posted by "Anonymitaet (via GitHub)" <gi...@apache.org>.
Anonymitaet commented on code in PR #674:
URL: https://github.com/apache/pulsar-site/pull/674#discussion_r1292885036
##########
docs/concepts-architecture-overview.md:
##########
@@ -75,20 +76,20 @@ Pulsar uses a system called [Apache BookKeeper](http://bookkeeper.apache.org/) f
* It's horizontally scalable in both capacity and throughput. Capacity can be immediately increased by adding more bookies to a cluster.
* Bookies are designed to handle thousands of ledgers with concurrent reads and writes. By using multiple disk devices---one for journal and another for general storage--bookies can isolate the effects of reading operations from the latency of ongoing write operations.
-In addition to message data, *cursors* are also persistently stored in BookKeeper. Cursors are [subscription](reference-terminology.md#subscription) positions for [consumers](reference-terminology.md#consumer). BookKeeper enables Pulsar to store consumer position in a scalable fashion.
+In addition to message data, *cursors* are also persistently stored in BookKeeper. Cursors are [subscription](concepts-messaging.md#subscriptions) positions for [consumers](concepts-clients.md#consumer). BookKeeper enables Pulsar to store consumer position in a scalable fashion.
At the moment, Pulsar supports persistent message storage. This accounts for the `persistent` in all topic names. Here's an example:
```http
persistent://my-tenant/my-namespace/my-topic
```
-> Pulsar also supports ephemeral ([non-persistent](concepts-messaging.md#non-persistent-topics) message storage.
+> Pulsar also supports ephemeral [non-persistent](concepts-messaging.md#non-persistent-topics) message storage.
You can see an illustration of how brokers and bookies interact in the diagram below:
-
+
Review Comment:
```suggestion
```
##########
docs/concepts-clients.md:
##########
@@ -55,13 +61,13 @@ You can set producer access mode through [Java Client API](/api/client/). For mo
A consumer is a process that attaches to a topic via a subscription and then receives messages.
-
+
Review Comment:
```suggestion
```
##########
docs/concepts-clients.md:
##########
@@ -12,18 +13,23 @@ Pulsar client libraries support transparent reconnection and/or connection failo
Before an application creates a producer/consumer, the Pulsar client library needs to initiate a setup phase including two steps:
-1. The client attempts to determine the owner of the topic by sending an HTTP lookup request to the broker. The request could reach one of the active brokers which, by looking at the (cached) zookeeper metadata knows who is serving the topic or, in case nobody is serving it, tries to assign it to the least loaded broker.
-2. Once the client library has the broker address, it creates a TCP connection (or reuses an existing connection from the pool) and authenticates it. Within this connection, the client and broker exchange binary commands from a custom protocol. At this point, the client sends a command to create producer/consumer to the broker, which will comply after having validated the authorization policy.
+1. The client attempts to determine the owner of the topic by sending an HTTP lookup request to the broker.
+
+ The request could reach one of the active brokers which, by looking at the (cached) zookeeper metadata knows who is serving the topic or, in case nobody is serving it, tries to assign it to the least loaded broker.
Review Comment:
```suggestion
The request could reach one of the active brokers which, by looking at the (cached) Zookeeper metadata knows who is serving the topic or, in case nobody is serving it, tries to assign it to the least loaded broker.
```
##########
docs/concepts-cluster-level-failover.md:
##########
@@ -36,19 +42,29 @@ Once the primary cluster functions again, Pulsar clients can switch back to the
The cluster-level failover provides fault tolerance, continuous availability, and high availability together. It brings a number of benefits, including but not limited to:
-* Reduced cost: services can be switched and recovered automatically with no data loss.
+* Reduced cost
+
+ services can be switched and recovered automatically with no data loss.
+
+* Simplified management
+
+ businesses can operate on an "always-on" basis since no immediate user intervention is required.
-* Simplified management: businesses can operate on an "always-on" basis since no immediate user intervention is required.
+* Improved stability and robustness
-* Improved stability and robustness: it ensures continuous performance and minimizes service downtime.
+ it ensures continuous performance and minimizes service downtime.
### When to use cluster-level failover?
The cluster-level failover protects your environment in a number of ways, including but not limited to:
-* Disaster recovery: cluster-level failover can automatically and seamlessly transfer the production workload on a primary cluster to one or several backup clusters, which ensures minimum data loss and reduced recovery time.
+* Disaster recovery
+
+ cluster-level failover can automatically and seamlessly transfer the production workload on a primary cluster to one or several backup clusters, which ensures minimum data loss and reduced recovery time.
-* Planned migration: if you want to migrate production workloads from an old cluster to a new cluster, you can improve the migration efficiency with cluster-level failover. For example, you can test whether the data migration goes smoothly in case of a failover event, identify possible issues and risks before the migration.
+* Planned migration
+
+ if you want to migrate production workloads from an old cluster to a new cluster, you can improve the migration efficiency with cluster-level failover. For example, you can test whether the data migration goes smoothly in case of a failover event, identify possible issues and risks before the migration.
Review Comment:
same question as above
##########
docs/concepts-cluster-level-failover.md:
##########
@@ -132,11 +160,13 @@ In an automatic failover cluster, the primary cluster and backup cluster are awa
3b) If the primary cluster does not come back, the Pulsar client does not perform the switchover.
-
+
</TabItem>
<TabItem value="Controlled cluster-level failover">
+The controlled failover cluster performs the following actions with administrator intervention:
Review Comment:
Good catch!
##########
docs/concepts-replication.md:
##########
@@ -39,24 +40,26 @@ Synchronous geo-replication provides the highest availability and also guarantee
## Replication patterns
-Pulsar provides a great degree of flexibility for customizing your replication strategy. You can set up different replication patterns to serve your replication strategy for an application between multiple data centers.
+Pulsar provides a great degree of flexibility for customizing your replication strategy. You can set up different replication patterns to serve your replication strategy for an application between multiple data centers.
+
+Pulsar supports the following three replication patterns:
Review Comment:
```suggestion
Pulsar supports the following replication patterns:
```
Avoid specifying specific NO. if there are more replication patterns to be supported in the future.
##########
docs/concepts-clients.md:
##########
@@ -32,7 +38,7 @@ Producers send messages to brokers synchronously (sync) or asynchronously (async
### Access mode
-You can have different types of access modes on topics for producers.
+Access mode determines the permissions of producers on topics.
Review Comment:
```suggestion
Access mode is a mechanism determining the permissions of producers on topics.
```
##########
docs/concepts-topic-compaction.md:
##########
@@ -23,14 +24,31 @@ Pulsar's topic compaction feature:
## How topic compaction works
-When topic compaction is triggered [via the CLI](cookbooks-compaction.md), Pulsar will iterate over the entire topic from beginning to end. For each key that it encounters the compaction routine will keep a record of the latest occurrence of that key.
+When topic compaction is triggered [via the CLI](cookbooks-compaction.md), it works in the following steps:
-After that, the broker will create a new [BookKeeper ledger](concepts-architecture-overview.md#ledgers) and make a second iteration through each message on the topic. For each message, if the key matches the latest occurrence of that key, then the key's data payload, message ID, and metadata will be written to the newly created ledger. If the key doesn't match the latest then the message will be skipped and left alone. If any given message has an empty payload, it will be skipped and considered deleted (akin to the concept of [tombstones](https://en.wikipedia.org/wiki/Tombstone_(data_store)) in key-value databases). At the end of this second iteration through the topic, the newly created BookKeeper ledger is closed and two things are written to the topic's metadata: the ID of the BookKeeper ledger and the message ID of the last compacted message (this is known as the **compaction horizon** of the topic). Once this metadata is written compaction is complete.
+1. Pulsar will iterate over the entire topic from beginning to end.
-After the initial compaction operation, the Pulsar [broker](reference-terminology.md#broker) that owns the topic is notified whenever any future changes are made to the compaction horizon and compacted backlog. When such changes occur:
+ For each key that it encounters the compaction routine will keep a record of the latest occurrence of that key.
-* Clients (consumers and readers) that have read compacted enabled will attempt to read messages from a topic and either:
- * Read from the topic like normal (if the message ID is greater than or equal to the compaction horizon) or
- * Read beginning at the compaction horizon (if the message ID is lower than the compaction horizon)
+2. After that, the broker will create a new [BookKeeper ledger](concepts-architecture-overview.md#ledgers) and make a second iteration through each message on the topic. For each message:
+
+ - if the key matches the latest occurrence of that key, then the key's data payload, message ID, and metadata will be written to the newly created ledger.
Review Comment:
```suggestion
- If the key matches the latest occurrence of that key, then the key's data payload, message ID, and metadata will be written to the newly created ledger.
```
##########
docs/concepts-throttling.md:
##########
@@ -64,7 +65,7 @@ The dispatch rate limits configured at multiple levels take effect simultaneousl
### Throttling approaches
-The following table outlines multiple approaches to configure the dispatch rate limits at different levels.
+The following table outlines multiple throttling approaches to configure the dispatch rate limits at different levels.
Review Comment:
```suggestion
You can use multiple throttling approaches to configure dispatch rate limits at different levels.
```
##########
docs/tutorials-tenant.md:
##########
@@ -5,7 +5,7 @@ sidebar_label: "Set up a tenant"
---
-Pulsar is a powerful messaging system you can use to process and route high volumes of data. Each tenant provides a distinct unit of isolation with its own set of roles, permissions, configuration settings, and bookmarks.
+Pulsar is a powerful messaging system you can use to process and route high volumes of data. Each t[enant](concepts-multi-tenancy.md#tenants) provides a distinct unit of isolation with its own set of roles, permissions, configuration settings, and bookmarks.
Review Comment:
```suggestion
Pulsar is a powerful messaging system you can use to process and route high volumes of data. Each [tenant](concepts-multi-tenancy.md#tenants) provides a distinct unit of isolation with its own set of roles, permissions, configuration settings, and bookmarks.
```
##########
docs/concepts-architecture-overview.md:
##########
@@ -144,13 +145,13 @@ Some important things to know about the Pulsar proxy:
## Service discovery
-[Clients](concepts-clients.md) connecting to Pulsar brokers need to be able to communicate with an entire Pulsar instance using a single URL.
+Service discovery is a mechanism provided by Pulsar that enables connecting [clients](concepts-clients.md) to use just a single URL to interact with an entire Pulsar instance.
Review Comment:
```suggestion
Service discovery is a mechanism that enables connecting [clients](concepts-clients.md) to use just a single URL to interact with an entire Pulsar instance.
```
##########
docs/concepts-clients.md:
##########
@@ -55,13 +61,13 @@ You can set producer access mode through [Java Client API](/api/client/). For mo
A consumer is a process that attaches to a topic via a subscription and then receives messages.
-
+
A consumer sends a [flow permit request](developing-binary-protocol.md#flow-control) to a broker to get messages. There is a queue at the consumer side to receive messages pushed from the broker. You can configure the queue size with the [`receiverQueueSize`](pathname:///reference/#/@pulsar:version_reference@/client/client-configuration-consumer?id=receiverqueuesize) parameter. The default size is `1000`). Each time `consumer.receive()` is called, a message is dequeued from the buffer.
### Receive mode
-Messages are received from [brokers](reference-terminology.md#broker) either synchronously (sync) or asynchronously (async).
+Receive mode determines whether messages are received from [brokers](concepts-architecture-overview.md#brokers) synchronously (sync) or asynchronously (async).
Review Comment:
```suggestion
Receive mode is a mechanism determining whether messages are received from [brokers](concepts-architecture-overview.md#brokers) synchronously (sync) or asynchronously (async).
```
##########
docs/concepts-cluster-level-failover.md:
##########
@@ -2,8 +2,14 @@
id: concepts-cluster-level-failover
title: Cluster-level failover
sidebar_label: "Cluster-level failover"
+description: Get a comprehensive understanding of the concept, benefits, use cases and more information about the cluster-level failover in Pulsar.
Review Comment:
```suggestion
description: Get a comprehensive understanding of concepts, benefits, and use cases about the cluster-level failover in Pulsar.
```
##########
docs/concepts-clients.md:
##########
@@ -12,18 +13,23 @@ Pulsar client libraries support transparent reconnection and/or connection failo
Before an application creates a producer/consumer, the Pulsar client library needs to initiate a setup phase including two steps:
-1. The client attempts to determine the owner of the topic by sending an HTTP lookup request to the broker. The request could reach one of the active brokers which, by looking at the (cached) zookeeper metadata knows who is serving the topic or, in case nobody is serving it, tries to assign it to the least loaded broker.
-2. Once the client library has the broker address, it creates a TCP connection (or reuses an existing connection from the pool) and authenticates it. Within this connection, the client and broker exchange binary commands from a custom protocol. At this point, the client sends a command to create producer/consumer to the broker, which will comply after having validated the authorization policy.
+1. The client attempts to determine the owner of the topic by sending an HTTP lookup request to the broker.
+
+ The request could reach one of the active brokers which, by looking at the (cached) zookeeper metadata knows who is serving the topic or, in case nobody is serving it, tries to assign it to the least loaded broker.
+
+2. Once the client library has the broker address, it creates a TCP connection (or reuses an existing connection from the pool) and authenticates it.
+
+ Within this connection, the client and broker exchange binary commands from a custom protocol. At this point, the client sends a command to create producer/consumer to the broker, which will comply after having validated the authorization policy.
Whenever the TCP connection breaks, the client immediately re-initiates this setup phase and keeps trying with exponential backoff to re-establish the producer or consumer until the operation succeeds.
## Producer
-A producer is a process that attaches to a topic and publishes messages to a Pulsar [broker](reference-terminology.md#broker). The Pulsar broker processes the messages.
+A producer is a process that attaches to a topic and publishes messages to a Pulsar [broker](concepts-architecture-overview.md#broker). The Pulsar broker processes the messages.
### Send mode
-Producers send messages to brokers synchronously (sync) or asynchronously (async).
+Send mode determines whether producers send messages to brokers synchronously (sync) or asynchronously (async).
Review Comment:
```suggestion
Send mode is a mechanism determining whether producers send messages to brokers synchronously (sync) or asynchronously (async).
```
##########
docs/concepts-authentication.md:
##########
@@ -2,6 +2,7 @@
id: concepts-authentication
title: Authentication and Authorization
sidebar_label: "Authentication and Authorization"
+description: Get a high level understanding of the concept of Authentication and Authorization in Pulsar.
Review Comment:
```suggestion
description: Get a high-level understanding of authentication and authorization in Pulsar.
```
Why capitalize "A"?
##########
docs/concepts-clients.md:
##########
@@ -94,7 +100,7 @@ Please also note that a reader can have a "backlog", but the metric is only used
:::
-
+
Review Comment:
```suggestion
```
##########
docs/concepts-architecture-overview.md:
##########
@@ -56,7 +57,7 @@ In a Pulsar instance:
## Configuration store
-The configuration store maintains all the configurations of a Pulsar instance, such as clusters, tenants, namespaces, partitioned topic-related configurations, and so on. A Pulsar instance can have a single local cluster, multiple local clusters, or multiple cross-region clusters. Consequently, the configuration store can share the configurations across multiple clusters under a Pulsar instance. The configuration store can be deployed on a separate ZooKeeper cluster or deployed on an existing ZooKeeper cluster.
+The Configuration store is a ZooKeeper quorum that is used for configuration-specific tasks and it maintains all the configurations of a Pulsar instance, such as clusters, tenants, namespaces, partitioned topic-related configurations, and so on. A Pulsar instance can have a single local cluster, multiple local clusters, or multiple cross-region clusters. Consequently, the configuration store can share the configurations across multiple clusters under a Pulsar instance. The configuration store can be deployed on a separate ZooKeeper cluster or deployed on an existing ZooKeeper cluster.
Review Comment:
```suggestion
The configuration store is a ZooKeeper quorum that is used for configuration-specific tasks and it maintains all the configurations of a Pulsar instance, such as clusters, tenants, namespaces, partitioned topic-related configurations, and so on. A Pulsar instance can have a single local cluster, multiple local clusters, or multiple cross-region clusters. Consequently, the configuration store can share the configurations across multiple clusters under a Pulsar instance. The configuration store can be deployed on a separate ZooKeeper cluster or deployed on an existing ZooKeeper cluster.
```
Why capitalize "C"?
##########
docs/concepts-cluster-level-failover.md:
##########
@@ -36,19 +42,29 @@ Once the primary cluster functions again, Pulsar clients can switch back to the
The cluster-level failover provides fault tolerance, continuous availability, and high availability together. It brings a number of benefits, including but not limited to:
-* Reduced cost: services can be switched and recovered automatically with no data loss.
+* Reduced cost
+
+ services can be switched and recovered automatically with no data loss.
+
+* Simplified management
+
+ businesses can operate on an "always-on" basis since no immediate user intervention is required.
-* Simplified management: businesses can operate on an "always-on" basis since no immediate user intervention is required.
+* Improved stability and robustness
-* Improved stability and robustness: it ensures continuous performance and minimizes service downtime.
+ it ensures continuous performance and minimizes service downtime.
Review Comment:
Why not capitalize the 1st letter of the 1st word in a sentence?
##########
docs/concepts-cluster-level-failover.md:
##########
@@ -60,13 +76,21 @@ The cluster-level failover protects your environment in a number of ways, includ
Automatic cluster-level failover is triggered when Pulsar clients cannot connect to the primary cluster for a prolonged period of time. This can be caused by any number of reasons including, but not limited to:
-* Network failure: internet connection is lost.
+* Network failure
+
+ internet connection is lost.
-* Power failure: shutdown time of a primary cluster exceeds time limits.
+* Power failure
-* Service error: errors occur on a primary cluster (for example, the primary cluster does not function because of time limits).
+ shutdown time of a primary cluster exceeds time limits.
-* Crashed storage space: the primary cluster does not have enough storage space, but the corresponding storage space on the backup server functions normally.
+* Service error
+
+ errors occur on a primary cluster (for example, the primary cluster does not function because of time limits).
+
+* Crashed storage space
+
+ the primary cluster does not have enough storage space, but the corresponding storage space on the backup server functions normally.
Review Comment:
same
##########
docs/concepts-cluster-level-failover.md:
##########
@@ -80,17 +104,21 @@ Controlled cluster-level failover is triggered when administrators set the switc
### Why does cluster-level failover fail?
-Obviously, the cluster-level failover does not succeed if the backup cluster is unreachable by active Pulsar clients. This can happen for many reasons, including but not limited to:
+Obviously, the cluster-level failover will fail if the backup cluster is unreachable by active Pulsar clients. This can happen for many reasons, including but not limited to:
Review Comment:
```suggestion
Obviously, the cluster-level failover does not succeed if the backup cluster is unreachable by active Pulsar clients. This can happen for many reasons, including but not limited to:
```
1. Avoid duplicate "fail"
2. Write in the simple present tense as much as possible if you are covering facts that were, are, and forever shall be true. https://docs.google.com/document/d/1lc5j4RtuLIzlEYCBo97AC8-U_3Erzs_lxpkDuseU0n4/edit#bookmark=id.e8uqh1awkcnp
##########
docs/concepts-multi-tenancy.md:
##########
@@ -16,14 +17,14 @@ As you can see, the tenant is the most basic unit of categorization for topics (
## Tenants
-To each tenant in a Pulsar instance you can assign:
+A Pulsar tenant is an administrative unit for allocating capacity and enforcing an authentication/authorization scheme. To each tenant in a Pulsar instance you can assign:
Review Comment:
```suggestion
A Pulsar tenant is an administrative unit for allocating capacity and enforcing an authentication or authorization scheme. To each tenant in a Pulsar instance, you can assign:
```
##########
docs/concepts-cluster-level-failover.md:
##########
@@ -80,17 +104,21 @@ Controlled cluster-level failover is triggered when administrators set the switc
### Why does cluster-level failover fail?
-Obviously, the cluster-level failover does not succeed if the backup cluster is unreachable by active Pulsar clients. This can happen for many reasons, including but not limited to:
+Obviously, the cluster-level failover will fail if the backup cluster is unreachable by active Pulsar clients. This can happen for many reasons, including but not limited to:
-* Power failure: the backup cluster is shut down or does not function normally.
+* Power failure
-* Crashed storage space: primary and backup clusters do not have enough storage space.
+ the backup cluster is shut down or does not function normally.
+
+* Crashed storage space
+
+ primary and backup clusters do not have enough storage space.
Review Comment:
same
##########
docs/concepts-throttling.md:
##########
@@ -48,7 +49,7 @@ The process of message dispatch throttling can be divided into the following ste
### Throttling levels
-The following table outlines the three levels that you can throttle message dispatch.
+Configuring throttling levels allows you to throttle message dispatch rate limits at multiple levels. The following table outlines the three throttling levels.
Review Comment:
```suggestion
You can set throttle message dispatch at different levels.
```
##########
docs/concepts-proxy-sni-routing.md:
##########
@@ -136,9 +137,9 @@ client = Client("pulsar+ssl://ats-proxy:443",
````
### Pulsar geo-replication with SNI routing
-You can use the ATS proxy for geo-replication. Pulsar brokers can connect to brokers in geo-replication by using SNI routing. To enable SNI routing for broker connection cross clusters, you need to configure SNI proxy URL to the cluster metadata. If you have configured SNI proxy URL in the cluster metadata, you can connect to broker cross clusters through the proxy over SNI routing.
+You can use the ATS proxy for geo-replication. Pulsar brokers can connect to brokers in geo-replication by using SNI routing. To enable SNI routing for broker connection cross clusters to implement geo-replication, you need to configure SNI proxy URL to the cluster metadata. If you have configured SNI proxy URL in the cluster metadata, you can connect to broker cross clusters through the proxy over SNI routing.
Review Comment:
```suggestion
You can use the ATS proxy for geo-replication. Pulsar brokers can connect to brokers in geo-replication by using SNI routing. To enable SNI routing for broker connection cross clusters, you need to configure SNI proxy URL to the cluster metadata. If you have configured SNI proxy URL in the cluster metadata, you can connect to broker cross clusters through the proxy over SNI routing.
```
Avoid length sentence
##########
docs/concepts-replication.md:
##########
@@ -39,24 +40,26 @@ Synchronous geo-replication provides the highest availability and also guarantee
## Replication patterns
-Pulsar provides a great degree of flexibility for customizing your replication strategy. You can set up different replication patterns to serve your replication strategy for an application between multiple data centers.
+Pulsar provides a great degree of flexibility for customizing your replication strategy. You can set up different replication patterns to serve your replication strategy for an application between multiple data centers.
+
+Pulsar supports the following three replication patterns:
### Full-mesh replication
Using full-mesh replication and applying the [selective message replication](administration-geo.md#selective-replication), you can customize your replication strategies and topologies between any number of data centers.
-
+
### Active-active replication
Active-active replication is a variation of full-mesh replication, with only two data centers. Producers can run at any data center to produce messages, and consumers can consume all messages from all data centers.
-
+
For how to use active-active replication to migrate data between clusters, refer to [here](administration-geo.md#migrate-data-between-clusters-using-geo-replication).
### Aggregation replication
-The aggregation replication pattern is typically used when replicating messages from the edge to the cloud. For example, assume you have 3 clusters in 3 fronting datacenters and one aggregated cluster in a central data center, and you want to replicate messages from multiple fronting datacenters to the central data center for aggregation purposes. You can then create an individual namespace for the topics used by each fronting data center and assign the aggregated data center to those namespaces.
+The aggregation replication pattern is typically used when replicating messages from the edge to the cloud. For example, assume you have 3 clusters in 3 fronting data centers and one aggregated cluster in a central data center, and you want to replicate messages from multiple fronting data centers to the central data center for aggregation purposes. You can then create an individual namespace for the topics used by each fronting data center and assign the aggregated data center to those namespaces.
Review Comment:
FYI: data center is also correct https://www.techtarget.com/searchdatacenter/definition/data-center#:~:text=A%20data%20center%20%2D%2D%20also,disseminate%20large%20amounts%20of%20data.
##########
docs/concepts-proxy-sni-routing.md:
##########
@@ -24,7 +25,7 @@ Pulsar supports SNI routing for geo-replication, so brokers can connect to broke
This section explains how to set up and use ATS as a reverse proxy, so Pulsar clients can connect to brokers through the ATS proxy using the SNI routing protocol on TLS connection.
### Set up ATS Proxy for layer-4 SNI routing
-To support layer 4 SNI routing, you need to configure the `records.conf` and `ssl_server_name.conf` files.
+To Set up ATS Proxy for layer 4 SNI routing, you need to configure the `records.conf` and `ssl_server_name.conf` files.
Review Comment:
```suggestion
To set up ATS proxy for layer 4 SNI routing, you need to configure the `records.conf` and `ssl_server_name.conf` files.
```
##########
docs/concepts-topic-compaction.md:
##########
@@ -23,14 +24,31 @@ Pulsar's topic compaction feature:
## How topic compaction works
-When topic compaction is triggered [via the CLI](cookbooks-compaction.md), Pulsar will iterate over the entire topic from beginning to end. For each key that it encounters the compaction routine will keep a record of the latest occurrence of that key.
+When topic compaction is triggered [via the CLI](cookbooks-compaction.md), it works in the following steps:
-After that, the broker will create a new [BookKeeper ledger](concepts-architecture-overview.md#ledgers) and make a second iteration through each message on the topic. For each message, if the key matches the latest occurrence of that key, then the key's data payload, message ID, and metadata will be written to the newly created ledger. If the key doesn't match the latest then the message will be skipped and left alone. If any given message has an empty payload, it will be skipped and considered deleted (akin to the concept of [tombstones](https://en.wikipedia.org/wiki/Tombstone_(data_store)) in key-value databases). At the end of this second iteration through the topic, the newly created BookKeeper ledger is closed and two things are written to the topic's metadata: the ID of the BookKeeper ledger and the message ID of the last compacted message (this is known as the **compaction horizon** of the topic). Once this metadata is written compaction is complete.
+1. Pulsar will iterate over the entire topic from beginning to end.
-After the initial compaction operation, the Pulsar [broker](reference-terminology.md#broker) that owns the topic is notified whenever any future changes are made to the compaction horizon and compacted backlog. When such changes occur:
+ For each key that it encounters the compaction routine will keep a record of the latest occurrence of that key.
-* Clients (consumers and readers) that have read compacted enabled will attempt to read messages from a topic and either:
- * Read from the topic like normal (if the message ID is greater than or equal to the compaction horizon) or
- * Read beginning at the compaction horizon (if the message ID is lower than the compaction horizon)
+2. After that, the broker will create a new [BookKeeper ledger](concepts-architecture-overview.md#ledgers) and make a second iteration through each message on the topic. For each message:
+
+ - if the key matches the latest occurrence of that key, then the key's data payload, message ID, and metadata will be written to the newly created ledger.
+
+ - If the key doesn't match the latest then the message will be skipped and left alone.
+
+ - If any given message has an empty payload, it will be skipped and considered deleted (akin to the concept of [tombstones](https://en.wikipedia.org/wiki/Tombstone_(data_store)) in key-value databases).
+
+3. At the end of this second iteration through the topic, the newly created BookKeeper ledger is closed and two things are written to the topic's metadata:
+
+ - the ID of the BookKeeper ledger
+ - the message ID of the last compacted message (this is known as the **compaction horizon** of the topic).
Review Comment:
same
##########
docs/concepts-topic-compaction.md:
##########
@@ -2,13 +2,14 @@
id: concepts-topic-compaction
title: Topic Compaction
sidebar_label: "Topic Compaction"
+descriptions: Get a comprehensive understanding of the concept, features and functioning of topic compaction in Apache Pulsar.
Review Comment:
```suggestion
descriptions: Get a comprehensive understanding of concepts, features, and workflow of topic compaction in Apache Pulsar.
```
--
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: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar-site] tisonkun commented on a diff in pull request #674: SEO for Concepts and Architecture except Overview and Messaging
Posted by "tisonkun (via GitHub)" <gi...@apache.org>.
tisonkun commented on code in PR #674:
URL: https://github.com/apache/pulsar-site/pull/674#discussion_r1292932500
##########
docs/reference-terminology.md:
##########
@@ -78,18 +67,6 @@ A group of namespaces that have anti-affinity to each other.
A lightweight Pulsar broker in which all components run in a single Java Virtual Machine (JVM) process. Standalone
clusters can be run on a single machine and are useful for development purposes.
-### Cluster
Review Comment:
Thanks for your explanation!
--
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: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar-site] zuobiao-zhou commented on pull request #674: SEO for Concepts and Architecture except Overview and Messaging
Posted by "zuobiao-zhou (via GitHub)" <gi...@apache.org>.
zuobiao-zhou commented on PR #674:
URL: https://github.com/apache/pulsar-site/pull/674#issuecomment-1676566229
fixed, PTAL @Anonymitaet
--
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: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar-site] zuobiao-zhou commented on pull request #674: seo for C&A
Posted by "zuobiao-zhou (via GitHub)" <gi...@apache.org>.
zuobiao-zhou commented on PR #674:
URL: https://github.com/apache/pulsar-site/pull/674#issuecomment-1674225774
cc @Anonymitaet
--
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: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org