Anonymitaet commented on code in PR #671: URL: https://github.com/apache/pulsar-site/pull/671#discussion_r1287830465
########## docs/concepts-messaging.md: ########## @@ -55,14 +56,19 @@ The default max size of a message is 5 MB. You can configure the max size of a m ### Acknowledgment -The consumer sends an acknowledgment request to the broker after it consumes a message successfully. Then, this consumed message will be permanently stored, and deleted only after all the subscriptions have acknowledged it. If you want to store the messages that have been acknowledged by a consumer, you need to configure the [message retention policy](concepts-messaging.md#message-retention-and-expiry). +A message Acknowledgment is sent by the consumer to the broker after it consumes a message successfully. Then, this consumed message will be permanently stored, and deleted only after all the subscriptions have acknowledged it. An acknowledgment (ack) is Pulsar's way of knowing that the message can be deleted from the system. If you want to store the messages that have been acknowledged by a consumer, you need to configure the [message retention policy](concepts-messaging.md#message-retention-and-expiry). Review Comment: ```suggestion A message acknowledgment is sent by a consumer to a broker after the consumer consumes a message successfully. Then, this consumed message will be permanently stored and deleted only after all the subscriptions have acknowledged it. An acknowledgment (ack) is Pulsar's way of knowing that the message can be deleted from the system. If no acknowledgment, then the message will be retained until it's processed. If you want to store the messages that have been acknowledged by a consumer, you need to configure the [message retention policy](concepts-messaging.md#message-retention-and-expiry). ``` ########## docs/concepts-messaging.md: ########## @@ -218,7 +224,7 @@ consumer.acknowledge(message); Retry letter topic allows you to store the messages that failed to be consumed and retry consuming them later. With this method, you can customize the interval at which the messages are redelivered. Consumers on the original topic are automatically subscribed to the retry letter topic as well. Once the maximum number of retries has been reached, the unconsumed messages are moved to a [dead letter topic](#dead-letter-topic) for manual processing. The functionality of a retry letter topic is implemented by consumers. The diagram below illustrates the concept of the retry letter topic. - + Review Comment: ```suggestion  ``` Articles / indefinite articles can be omitted in alt tags to keep it more concise. ########## docs/concepts-messaging.md: ########## @@ -2,6 +2,7 @@ id: concepts-messaging title: Messaging sidebar_label: "Messaging" +description: Apache Pulsar is built on the publish-subscribe pattern. Producers, messages, topics, brokers, and consumers together constitute this messaging system. Review Comment: ```suggestion description: get a comprehensive understanding of essential messaging concepts within Pulsar, including topics, namespaces, subscriptions, and more. ``` ########## docs/concepts-messaging.md: ########## @@ -389,9 +395,9 @@ client.newProducer() ### Batching -When batching is enabled, the producer accumulates and sends a batch of messages in a single request. The batch size is defined by the maximum number of messages and the maximum publish latency. Therefore, the backlog size represents the total number of batches instead of the total number of messages. +In Pulsar, batching means the producer accumulates and sends a batch of messages in a single request. The batch size is defined by the maximum number of messages and the maximum publish latency. Therefore, the backlog size represents the total number of batches instead of the total number of messages. Review Comment: Suggest keeping the original text unchanged since it's accurate ########## docs/concepts-messaging.md: ########## @@ -435,13 +441,13 @@ With message chunking enabled, when the size of a message exceeds the allowed ma The following figure shows a topic with one producer that publishes a large message payload in chunked messages along with regular non-chunked messages. The producer publishes message M1 in three chunks labeled M1-C1, M1-C2 and M1-C3. The broker stores all the three chunked messages in the [managed ledger](concepts-architecture-overview.md#managed-ledgers) and dispatches them to the ordered (exclusive/failover) consumer in the same order. The consumer buffers all the chunked messages in memory until it receives all the chunked messages, aggregates them into one message and then hands over the original message M1 to the client. - + Review Comment: ```suggestion  ``` Only keep most frequently used keywords ########## docs/concepts-messaging.md: ########## @@ -464,7 +470,7 @@ If the consumer fails to receive all chunks of a message within a specified peri ## Topics -As in other pub-sub systems, topics in Pulsar are named channels for transmitting messages from producers to consumers. Topic names are URLs that have a well-defined structure: +A Pulsar topic is a unit of storage that organizes messages into a stream. As in other pub-sub systems, topics in Pulsar are named channels for transmitting messages from producers to consumers. Topic names are URLs that have a well-defined structure: Review Comment: Please update the relevant file (e.g., https://pulsar.apache.org/docs/next/tutorials-topic/) in the same PR to prevent omissions. <img width="1212" alt="image" src="https://github.com/apache/pulsar-site/assets/50226895/84cf88d2-b645-4355-8a9a-34ce2dbb6c9d";> ########## docs/concepts-messaging.md: ########## @@ -435,13 +441,13 @@ With message chunking enabled, when the size of a message exceeds the allowed ma The following figure shows a topic with one producer that publishes a large message payload in chunked messages along with regular non-chunked messages. The producer publishes message M1 in three chunks labeled M1-C1, M1-C2 and M1-C3. The broker stores all the three chunked messages in the [managed ledger](concepts-architecture-overview.md#managed-ledgers) and dispatches them to the ordered (exclusive/failover) consumer in the same order. The consumer buffers all the chunked messages in memory until it receives all the chunked messages, aggregates them into one message and then hands over the original message M1 to the client. - + #### Handle interwoven chunked messages with one ordered consumer When multiple producers publish chunked messages into a single topic, the broker stores all the chunked messages coming from different producers in the same [managed ledger](concepts-architecture-overview.md#managed-ledgers). The chunked messages in the managed ledger can be interwoven with each other. As shown below, Producer 1 publishes message M1 in three chunks M1-C1, M1-C2 and M1-C3. Producer 2 publishes message M2 in three chunks M2-C1, M2-C2 and M2-C3. All chunked messages of the specific message are still in order but might not be consecutive in the managed ledger. - + Review Comment: ```suggestion  ``` ########## docs/concepts-messaging.md: ########## @@ -389,9 +395,9 @@ client.newProducer() ### Batching -When batching is enabled, the producer accumulates and sends a batch of messages in a single request. The batch size is defined by the maximum number of messages and the maximum publish latency. Therefore, the backlog size represents the total number of batches instead of the total number of messages. +In Pulsar, batching means the producer accumulates and sends a batch of messages in a single request. The batch size is defined by the maximum number of messages and the maximum publish latency. Therefore, the backlog size represents the total number of batches instead of the total number of messages. - + Review Comment: ```suggestion  ``` ########## docs/concepts-messaging.md: ########## @@ -486,13 +492,20 @@ If no tenant or namespace is specified when a client creates a topic, the topic ## Namespaces -A namespace is a logical nomenclature within a tenant. A tenant creates namespaces via the [admin API](admin-api-namespaces.md#create-namespaces). For instance, a tenant with different applications can create a separate namespace for each application. A namespace allows the application to create and manage a hierarchy of topics. The topic `my-tenant/app1` is a namespace for the application `app1` for `my-tenant`. You can create any number of [topics](#topics) under the namespace. +Pulsar namespaces are logical groupings of topics. A namespace is a logical nomenclature within a tenant. A tenant creates namespaces via the [admin API](admin-api-namespaces.md#create-namespaces). For instance, a tenant with different applications can create a separate namespace for each application. A namespace allows the application to create and manage a hierarchy of topics. The topic `my-tenant/app1` is a namespace for the application `app1` for `my-tenant`. You can create any number of [topics](#topics) under the namespace. Review Comment: ```suggestion A Pulsar namespace is a logical grouping of topics as well as a logical nomenclature within a tenant. A tenant creates namespaces via the [admin API](admin-api-namespaces.md#create-namespaces). For instance, a tenant with different applications can create a separate namespace for each application. A namespace allows the application to create and manage a hierarchy of topics. The topic `my-tenant/app1` is a namespace for the application `app1` for `my-tenant`. You can create any number of [topics](#topics) under the namespace. ``` -- 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]
