docs: fetch read coalescing (DOC-2386)#1821
Conversation
New consume-data page for the 26.2 opt-in per-shard fetch read coalescer: concept, enable procedure, hit-ratio evaluation guidance, and limitations. Adds a nav entry and an env-gated cross-link TIP on the follower-fetching page (single-sourced; cloud build unaffected). Sourced from the engineering TOI (cupboard engineering/core/toi/v26.2/2026-07-21-fetch-read-coalescing.md). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
✅ Deploy Preview for redpanda-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Reword the enable guidance (disabled by default, little-to-no benefit) and add an intro sentence to Limitations. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Per SME (Brandon Allard), the feature can be enabled on BYOC and Dedicated clusters. Wrap the page in a single-source tag with env gating: cloud gets an availability line, the enable procedure with a pointer to cloud cluster configuration, and the limitations; the internal-metrics evaluation section is excluded from the cloud build (only public_metrics is customer-visible in Cloud). Companion stub: cloud-docs#645. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
|
||
| When many consumers fetch the same partition at the same offset concurrently (high read fan-out), the broker does redundant work: each fetch performs its own log read, its own serialization, and allocates its own copy of the response bytes. With a fan-out of N consumers, that is roughly N times the read CPU and N times the fetch-response memory for byte-identical output. | ||
|
|
||
| Fetch read coalescing removes that redundancy. The broker reads and serializes each unique read once, and shares the single result with every concurrent (and eligible back-to-back) consumer of the same data: one read, one serialization, one buffer, fanned out to all requesters. Under aligned fan-out, read CPU and fetch-response memory drop from roughly N times to one. |
There was a problem hiding this comment.
Not sure what Under aligned fan-out means in the last sentence here; there is no reference/mention to what it means for fanout to be aligned prior to this.
There was a problem hiding this comment.
Fair catch — "aligned fan-out" was shorthand this page invented and never defined. It was meant to describe the ideal case where the concurrent fetches are duplicates of each other: same partition, same offset, same fetch settings, so every fetch can share one read. Fixed in 8324dec by spelling that out instead of naming it: the sentence now reads "When all N consumers fetch the same partition at the same offset with the same fetch settings, read CPU and fetch-response memory drop from roughly N times to one." Also replaced the matching "misaligned or low fan-out" phrasing later on the page with plain language (consumers at different offsets, or few consumers per partition).
| ifdef::env-cloud[] | ||
| Fetch read coalescing is available on BYOC and Dedicated clusters. | ||
|
|
||
| Fetch read coalescing is disabled by default. Enable it when many consumers tail the same partitions with the same fetch settings, for example fan-out delivery of one stream to many downstream applications. Workloads with misaligned or low fan-out see little-to-no benefit and should leave it disabled. |
There was a problem hiding this comment.
Note that cloud users can't enable this themselves AFAIK. Maybe it is something they should be able to do though. Let me look into whitelisting the config option for user control.
There was a problem hiding this comment.
I will update to make this clear. If you end up whitelisting this option for user control before we release, please let me know asap. thx.
| Fetch read coalescing is disabled by default. Enable it when many consumers tail the same partitions with the same fetch settings, for example fan-out delivery of one stream to many downstream applications. Workloads with misaligned or low fan-out see little-to-no benefit and should leave it disabled. See <<Evaluate coalescing effectiveness>> for how to measure whether it helps your workload. | ||
| endif::[] | ||
|
|
||
| == How fetch read coalescing works |
There was a problem hiding this comment.
Do we normally give in-depth details on how a particular feature is implemented in our docs?
There was a problem hiding this comment.
We do, or at least that is the goal. This is now a standard part of the doc template we feed to Claude, and it creates a consistent experience for users regardless of what feature they are reading about. We found that users wanted/needed more context about features--what is this? What does it do? How do I use it? When should I use it? And how does it work? Of course, we try to keep it fairly high-level.
Are you thinking that this material should not be in the doc?
There was a problem hiding this comment.
It's fine as-is, my only thought is that the way the feature is implement is likely to change more frequently than the intention/goal of the feature. So its something that could become stale in future updates and you folks aren't pinged for any changes outside of src/v/config AFAIK.
| * *Obligatory and strict reads are grouped apart.* A single partition and offset fetched both ways at the same time incurs one duplicate read by design. | ||
| * *Retention is best-effort.* Completed results are only reusable by later readers while a fetch still references them; the coalescer never keeps a result alive on its own. The reliable savings are on genuinely concurrent readers of the same data, and back-to-back reuse is opportunistic. | ||
| * *Per-shard scope.* Coalescing collapses only the fan-out that lands on the same shard. Where consumers are spread across replicas and shards, for example with follower fetching, each shard coalesces the fan-out local to it. | ||
| * *It is a de-duplication mechanism, not a throughput mechanism.* Coalescing reduces read CPU and fetch-response memory; it does not change where reads land or reduce the total volume of unique reads. |
There was a problem hiding this comment.
Not sure if this last point is entirely accurate or needed.
There was a problem hiding this comment.
K--I'll remove it.
|
In addition to my other comments it's likely worth making a note somewhere that fetch coalescing should only be enabled for high fanout workloads. Enabling it for workloads with 1:1 or 1:2 fanout will likely result in higher reactor util due to the overhead the de-duplication logic introduces. |
The term was invented by this page and never defined; spell out the condition instead (same partition, same offset, same fetch settings). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Per ballard26's review: kafka_fetch_read_coalescing_enabled is not whitelisted for user control in Redpanda Cloud. Gate the rpk procedure to Self-Managed and route cloud readers to Redpanda Support. Revert to self-serve wording if the property is whitelisted before release. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Per ballard26: the de-duplication logic runs on every fetch read, so 1:1 or 1:2 fan-out likely increases reactor utilization. Strengthen the enable guidance in both env variants and add a limitations bullet. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Added in 66eed08 — and worth being loud about, since the page previously undersold this as "little-to-no benefit": the enable guidance in both the Self-Managed and Cloud variants now says to enable/request coalescing only for high fan-out workloads because at low fan-out (one or two consumers per partition) the de-duplication overhead can increase reactor utilization, and there's a new Limitations bullet making the same point where readers check before enabling. |
Per leadership decision: add the enterprise-license NOTE and a license prerequisite to the page (Self-Managed only; Cloud portions unchanged), and list the feature in the Enterprise features table. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2 participants
Resolves https://redpandadata.atlassian.net/browse/DOC-2386
Adds documentation for fetch read coalescing, the opt-in per-shard fetch read coalescer new in 26.2 that removes redundant read CPU and fetch-response memory under high consumer fan-out.
Changes
modules/develop/pages/consume-data/fetch-read-coalescing.adoc: contextualized intro (theN×→1× redundancy story and an explicit use-when), how it works (coalescing key, the ready-hit/in-flight-hit/miss outcomes, weak retention, per-shard scope), enable procedure (kafka_fetch_read_coalescing_enabled, live toggle, ~0.5 MB/shard cache), an Evaluate coalescing effectiveness section with the fourvectorized_kafka_fetch_read_coalescer_*counters and the hit-ratio formula for judging workload fit, and limitations.follower-fetching.adoc: anifndef::env-cloud[]-gated TIP cross-linking the new page (that page is single-sourced to cloud-docs; the new page is docs-only, so the cloud build never parses the xref).All content is sourced from the engineering TOI: engineering/core/toi/v26.2/2026-07-21-fetch-read-coalescing.md (Brandon Allard, SME), and verified against the implementation PR redpanda#31010 (merged to dev 2026-07-13, 26.2-only, no backports): property description, coalescing-key definition, obligatory-vs-strict duplicate-read caveat, and weak-retention behavior all match the source.
Single-sourcing for Redpanda Cloud (added after SME input)
Per Brandon Allard: fetch read coalescing can be enabled on BYOC and Dedicated clusters, so the page is now single-sourced:
// tag::single-source[]wraps the page; companion stub PR: cloud-docs#645 (draft — must merge only after this content reaches docsmainat 26.2 promotion, since cloud-docs consumesstreamingfrommain).ifndef::env-cloud[]-gated: Cloud exposes onlypublic_metricsto customers, and the coalescer counters are internalvectorized_*metrics. (Worth a Brandon confirmation that there's no Cloud-side visibility planned.)follower-fetching.adocstaysifndef::env-cloud[]-gated for now; un-gating it is a follow-up after the cloud stub merges (otherwise the cloud build gets an xref to a page that doesn't exist there yet).Review notes
kafka_fetch_read_coalescing_enabledis not yet in the generated cluster-properties partial (arrives with the 26.2 property regen), so the page mentions it in code font without an xref; the link can be added after regen.🤖 Generated with Claude Code
Preview pages