[fix][doc] Describe approximate behavior of time-based quotas #412
Conversation
Link to config Older versions
docs/cookbooks-retention-expiry.md
Outdated
| @@ -214,6 +214,8 @@ Backlog quotas are handled at the namespace level. They can be managed via: | |||
|
|
|||
| You can set a size and/or time threshold and backlog retention policy for all of the topics in a [namespace](reference-terminology.md#namespace) by specifying the namespace, a size limit and/or a time limit in second, and a policy by name. | |||
|
|
|||
| Note that by default, time-based backlogs are enforced periodically using an approximate method. This avoids a potentially costly scan of the backlog each time a message is produced. However, it does mean that in some cases you may observe a lack of strict enforcement. To tune this behavior you should consider using the [`backlogQuotaCheckIntervalInSeconds`][backlogquotacheckintervalinseconds] and [`preciseTimeBasedBacklogQuotaCheck`][precisetimebasedbacklogquotacheck] broker options. | |||
There was a problem hiding this comment.
| Note that by default, time-based backlogs are enforced periodically using an approximate method. This avoids a potentially costly scan of the backlog each time a message is produced. However, it does mean that in some cases you may observe a lack of strict enforcement. To tune this behavior you should consider using the [`backlogQuotaCheckIntervalInSeconds`][backlogquotacheckintervalinseconds] and [`preciseTimeBasedBacklogQuotaCheck`][precisetimebasedbacklogquotacheck] broker options. | |
| ::: note | |
| By default, time-based backlogs are enforced periodically using an approximate method. This avoids a potentially costly scan of the backlog each time a message is produced. However, it does mean that in some cases you may observe a lack of strict enforcement. To tune this behavior, you should consider using the [`backlogQuotaCheckIntervalInSeconds`][backlogquotacheckintervalinseconds] and [`preciseTimeBasedBacklogQuotaCheck`][precisetimebasedbacklogquotacheck] broker options. | |
| ::: |
There was a problem hiding this comment.
This suggestions apply to other md files as well. Can you update them all?
Co-authored-by: Anonymitaet <50226895+Anonymitaet@users.noreply.github.com>
| @@ -214,6 +214,12 @@ Backlog quotas are handled at the namespace level. They can be managed via: | |||
|
|
|||
| You can set a size and/or time threshold and backlog retention policy for all of the topics in a [namespace](reference-terminology.md#namespace) by specifying the namespace, a size limit and/or a time limit in second, and a policy by name. | |||
|
|
|||
| ::: note | |||
|
|
|||
| By default, time-based backlogs are enforced periodically using an approximate method. This avoids a potentially costly scan of the backlog each time a message is produced. However, it does mean that in some cases you may observe a lack of strict enforcement. To tune this behavior, you should consider using the [`backlogQuotaCheckIntervalInSeconds`][backlogquotacheckintervalinseconds] and [`preciseTimeBasedBacklogQuotaCheck`][precisetimebasedbacklogquotacheck] broker options. | |||
There was a problem hiding this comment.
what does this mean?
[
xxx][xxx]
Do you want to highlight the para? You can use xxx instead.
There was a problem hiding this comment.
Those are links:
https://www.markdownguide.org/basic-syntax/#reference-style-links
| [backlogquotacheckintervalinseconds]: https://pulsar.apache.org/reference/#/next/config/reference-configuration-broker?id=backlogquotacheckintervalinseconds | ||
| [precisetimebasedbacklogquotacheck]: https://pulsar.apache.org/reference/#/next/config/reference-configuration-broker?id=precisetimebasedbacklogquotacheck |
There was a problem hiding this comment.
- What's the context of these two paras? Do you intend mean this?
| [backlogquotacheckintervalinseconds]: https://pulsar.apache.org/reference/#/next/config/reference-configuration-broker?id=backlogquotacheckintervalinseconds | |
| [precisetimebasedbacklogquotacheck]: https://pulsar.apache.org/reference/#/next/config/reference-configuration-broker?id=precisetimebasedbacklogquotacheck | |
| To configure checks, you can use `backlogquotacheckintervalinseconds` and | |
| `precisetimebasedbacklogquotacheck` parameters. Details see **Configuration > Plusar > Broker** on [Pulsar Reference Site](https://pulsar.apache.org/reference). |
- Suggest using general link (https://pulsar.apache.org/reference) instead of specific links to reduce maintenance costs and potential errors. We've applied this strategy across all docs.
There was a problem hiding this comment.
I disagree with this practice. It may be easier for authors, but it's really difficult for readers to find what they need. The target page has 100s of elements, is nested, is not searchable, and is not sorted.
I see in your suggestion that you still provide context to the reader "see Configuration > Plusar > Broker" — doesn't this too suffer from the same issues of maintenance and errors, while also being less useful by not being encoded in the link?
There was a problem hiding this comment.
This comment was left two weeks ago. The reason for my suggestion (as a temporary workaround) at that time was:
For example, if we want to publish a new next code release (2.12.0) with docs, the whole 2.12.x doc set is copied from master. If we use xxx/next/xxx in links, then the links in the old doc set will always point to the latest Reference site, which is incorrect.
< < < < < < < < < < < < < < < <
But now you can write it as [precisetimebasedbacklogquotacheck]: https://pulsar.apache.org/reference/#/@pulsar:version_origin@/config/reference-configuration-broker?id=precisetimebasedbacklogquotacheck since #456 was merged yesterday.
| @@ -214,6 +214,12 @@ Backlog quotas are handled at the namespace level. They can be managed via: | |||
|
|
|||
| You can set a size and/or time threshold and backlog retention policy for all of the topics in a [namespace](reference-terminology.md#namespace) by specifying the namespace, a size limit and/or a time limit in second, and a policy by name. | |||
|
|
|||
| ::: note | |||
There was a problem hiding this comment.
| ::: note | |
| :::note |
|
Code conflict and stale for a while. I'd close this PR and feel free to recreate a PR based on the latest master and ping me for review. |
|
Note that it doesn't mean this PR is rejected - it's good to have. Just a notification to roll up the stale PR. |
Time-based quotas are applied approximately. Yet the documentation supposes they are strict. It would be useful to set proper user expectations.
Documentation
docdoc-requireddoc-not-neededdoc-complete