Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[fix][doc] correct configuration name to exposingBrokerEntryMetadataToClientEnabled #17099

Merged
merged 3 commits into from
Aug 18, 2022

Conversation

Anonymitaet
Copy link
Member

@Anonymitaet Anonymitaet commented Aug 15, 2022

Fix #13336 (review)

I do not fix occurrences in reference-configuration.md because we're optimizing the workflow (trying to generate docs from code automatically for https://pulsar.apache.org/docs/next/reference-configuration)

  • doc

@Anonymitaet Anonymitaet added the doc Your PR contains doc changes, no matter whether the changes are in markdown or code files. label Aug 15, 2022
@Anonymitaet Anonymitaet added this to the 2.11.0 milestone Aug 15, 2022
@Anonymitaet Anonymitaet self-assigned this Aug 15, 2022
@@ -68,7 +68,7 @@ If you want to use broker entry metadata for **consumers**:

1. Use the client protocol version [18 or later](https://github.com/apache/pulsar/blob/ca37e67211feda4f7e0984e6414e707f1c1dfd07/pulsar-common/src/main/proto/PulsarApi.proto#L259).

2. Configure the [`brokerEntryMetadataInterceptors`](reference-configuration.md#broker) parameter and set the [`enableExposingBrokerEntryMetadataToClient`](reference-configuration.md#broker) parameter to `true` in the `broker.conf` file.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The brokerEntryMetadataInterceptors should not appear before V2.10.0. It's the same with #17004

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

brokerEntryMetadataInterceptors was introduced since 2.8.0, but enableExposingBrokerEntryMetadataToClient was introduced since 2.10.0.

Copy link
Contributor

@Huanli-Meng Huanli-Meng left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@Anonymitaet
Copy link
Member Author

@BewareMyPower
Double check: I've updated enableExposingBrokerEntryMetadataToClient for these versions, is it correct?

image

@Anonymitaet
Copy link
Member Author

ping @BewareMyPower again :-D

Copy link
Contributor

@BewareMyPower BewareMyPower left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you check this comment?

@Anonymitaet
Copy link
Member Author

Anonymitaet commented Aug 17, 2022

@RobertIndie @BewareMyPower thanks for your suggestions!

I've updated this PR based on your comments. The changes are summarized below, PTAL.

  1. Keep the following content for 2.8.x and 2.9.x.
## Broker entry metadata

Broker entry metadata is stored alongside the message metadata as a serialized protobuf message.
It is created by the broker when the message arrived at the broker and passed without changes to the consumer if configured.

| Field              | Required or optional       | Description                                                                                                                   |
|:-------------------|:----------------|:------------------------------------------------------------------------------------------------------------------------------|
| `broker_timestamp` | Optional        | The timestamp when a message arrived at the broker (`id est` as the number of milliseconds since January 1st, 1970 in UTC)      |
| `index`            | Optional        | The index of the message. It is assigned by the broker.

If you want to use broker entry metadata for **brokers**, configure the [`brokerEntryMetadataInterceptors`](reference-configuration.md#broker) parameter in the `broker.conf` file.
  1. Keep the following content for 2.10.x.
## Broker entry metadata

Broker entry metadata is stored alongside the message metadata as a serialized protobuf message.
It is created by the broker when the message arrived at the broker and passed without changes to the consumer if configured.

| Field              | Required or optional       | Description                                                                                                                   |
|:-------------------|:----------------|:------------------------------------------------------------------------------------------------------------------------------|
| `broker_timestamp` | Optional        | The timestamp when a message arrived at the broker (`id est` as the number of milliseconds since January 1st, 1970 in UTC)      |
| `index`            | Optional        | The index of the message. It is assigned by the broker.

If you want to use broker entry metadata for **brokers**, configure the [`brokerEntryMetadataInterceptors`](reference-configuration.md#broker) parameter in the `broker.conf` file.

If you want to use broker entry metadata for **consumers**:

1. Use the client protocol version [18 or later](https://github.com/apache/pulsar/blob/ca37e67211feda4f7e0984e6414e707f1c1dfd07/pulsar-common/src/main/proto/PulsarApi.proto#L259).
   
2. Configure the [`brokerEntryMetadataInterceptors`](reference-configuration.md#broker) parameter and set the [`exposingBrokerEntryMetadataToClientEnabled`](reference-configuration-broker.md#exposingbrokerentrymetadatatoclientenabled) parameter to `true` in the `broker.conf` file.
  1. Remove the following content for versions prior to 2.8.0.
## Broker entry metadata

Broker entry metadata is stored alongside the message metadata as a serialized protobuf message.
It is created by the broker when the message arrived at the broker and passed without changes to the consumer if configured.

| Field              | Required or optional       | Description                                                                                                                   |
|:-------------------|:----------------|:------------------------------------------------------------------------------------------------------------------------------|
| `broker_timestamp` | Optional        | The timestamp when a message arrived at the broker (`id est` as the number of milliseconds since January 1st, 1970 in UTC)      |
| `index`            | Optional        | The index of the message. It is assigned by the broker.

If you want to use broker entry metadata for **brokers**, configure the [`brokerEntryMetadataInterceptors`](reference-configuration.md#broker) parameter in the `broker.conf` file.

If you want to use broker entry metadata for **consumers**:

1. Use the client protocol version [18 or later](https://github.com/apache/pulsar/blob/ca37e67211feda4f7e0984e6414e707f1c1dfd07/pulsar-common/src/main/proto/PulsarApi.proto#L259).
   
2. Configure the [`brokerEntryMetadataInterceptors`](reference-configuration.md#broker) parameter and set the [`exposingBrokerEntryMetadataToClientEnabled`](reference-configuration-broker.md#exposingbrokerentrymetadatatoclientenabled) parameter to `true` in the `broker.conf` file.
  1. Ignore updating the versions in red and only updating versions in green since reds are deprecated. Details see Update versioned docs.

image

cc @momo-jun

@BewareMyPower
Copy link
Contributor

I found another problem when I reviewed this PR but it's not related. I found some versioned docs contain both develop-binary-protocol.md and developing-binary-protocol.md. I compared these two files in version-2.9.1 directory (after applying changes of this PR), they are nearly the same.

2c2
< id: develop-binary-protocol
---
> id: developing-binary-protocol
5c5
< original_id: develop-binary-protocol
---
> original_id: developing-binary-protocol
400a401,425
>  * `properties` → *(optional)* Reserved configuration items
>  * `txnid_most_bits` → *(optional)* Same as Transaction Coordinator ID, `txnid_most_bits` and `txnid_least_bits`
>    uniquely identify a transaction.
>  * `txnid_least_bits` → *(optional)* The ID of the transaction opened in a transaction coordinator,
>    `txnid_most_bits` and `txnid_least_bits`uniquely identify a transaction.
>  * `request_id` → *(optional)* ID for handling response and timeout.
> 
> 
>  ##### Command AckResponse
> 
> An `AckResponse` is the broker’s response to acknowledge a request sent by the client. It contains the `consumer_id` sent in the request.
> If a transaction is used, it contains both the Transaction ID and the Request ID that are sent in the request. The client finishes the specific request according to the Request ID. If the `error` field is set, it indicates that the request has failed.
> 
> An example of `AckResponse` with redirection:
> 
> ```protobuf
> 
> message CommandAckResponse {
>     "consumer_id" : 1,
>     "txnid_least_bits" = 0,
>     "txnid_most_bits" = 1,
>     "request_id" = 5
> }
> 
> ```
461c486
< Lookup can be done with a REST call as described in the [admin API](admin-api-topics.md#look-up-topics-owner-broker)
---
> Lookup can be done with a REST call as described in the [admin API](admin-api-topics.md#lookup-of-topic)

Could we delete the develop-binary-protocol.md?

@Anonymitaet
Copy link
Member Author

@BewareMyPower thank you! Suggest keeping it since there might be potential issues if it's removed.

Besides, keeping it does not cause trouble for doc maintainers since there is only developing-binary-protocol.md (no develop-binary-protocol.md) in version-2.8.x, version-2.9.x, version-2.10.x, master, and versions forward.

@Anonymitaet Anonymitaet merged commit e60e809 into apache:master Aug 18, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Your PR contains doc changes, no matter whether the changes are in markdown or code files.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants