cloud-topics: Add producer settings page#1695
Open
StephanDollberg wants to merge 1 commit into
Open
Conversation
✅ Deploy Preview for redpanda-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
|
Important Review skippedAuto incremental reviews are disabled on this repository. 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:
📝 WalkthroughWalkthroughThis PR adds comprehensive documentation for tuning Redpanda Cloud Topics producers on the client side. A new page titled "Configure Producers for Cloud Topics" explains theoretical throughput constraints under idempotency, provides concrete settings recommendations for Java clients and librdkafka, and describes the trade-offs of batching behavior. The Cloud Topics overview page is updated with a link to this new guidance, and the main navigation structure is modified to surface the new page under the develop:manage-topics section. Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
modules/develop/pages/manage-topics/cloud-topics.adoc (1)
86-86: ⚡ Quick winUse auto-title xref style for this new link.
Prefer empty brackets here so the link text stays in sync with the target page title.
Suggested edit
-For client-side tuning guidance, see xref:ROOT:develop:manage-topics/configure-producers-for-cloud-topics.adoc[Configure Producers for Cloud Topics]. +For client-side tuning guidance, see xref:ROOT:develop:manage-topics/configure-producers-for-cloud-topics.adoc[].Based on learnings: “AsciiDoc linking: prefer using xref links with empty brackets … avoid hard-coding link text.”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@modules/develop/pages/manage-topics/cloud-topics.adoc` at line 86, The current xref uses explicit link text; change it to the auto-title xref form so the link text stays synced with the target page by replacing xref:ROOT:develop:manage-topics/configure-producers-for-cloud-topics.adoc[Configure Producers for Cloud Topics] with xref:ROOT:develop:manage-topics/configure-producers-for-cloud-topics.adoc[] in cloud-topics.adoc (the link on the client-side tuning guidance line).
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
`@modules/develop/pages/manage-topics/configure-producers-for-cloud-topics.adoc`:
- Around line 24-30: Add an explicit bullet for request_size to the variable
list: define request_size as the effective produce request payload size measured
in bytes (i.e., the average payload size the client sends per produce request),
and state that this is the tunable client-controlled value used in the
throughput formula alongside broker_count, max_in_flight, and latency_seconds so
there is no ambiguity about units or meaning.
---
Nitpick comments:
In `@modules/develop/pages/manage-topics/cloud-topics.adoc`:
- Line 86: The current xref uses explicit link text; change it to the auto-title
xref form so the link text stays synced with the target page by replacing
xref:ROOT:develop:manage-topics/configure-producers-for-cloud-topics.adoc[Configure
Producers for Cloud Topics] with
xref:ROOT:develop:manage-topics/configure-producers-for-cloud-topics.adoc[] in
cloud-topics.adoc (the link on the client-side tuning guidance line).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: d883e0f3-2f85-4d7e-987b-bd697ea83729
📒 Files selected for processing (3)
modules/ROOT/nav.adocmodules/develop/pages/manage-topics/cloud-topics.adocmodules/develop/pages/manage-topics/configure-producers-for-cloud-topics.adoc
Comment on lines
+24
to
+30
| with the following definitions: | ||
|
|
||
| * `broker_count`: The number of brokers in the cluster. | ||
| * `max_in_flight`: The maximum number of in-flight requests on a single connection. With an idempotent producer, this is usually 5. | ||
| * `latency_seconds`: The latency of a single produce request. Assuming normal operation, this can be equated to the 250ms as described above. In practice, it will mostly be lower, as the timer starts with the first byte arriving. | ||
|
|
||
| Finally, we have `request_size`. This is the most important property from a tuning perspective, as it's under client control while the others are effectively constants. |
Contributor
There was a problem hiding this comment.
Define request_size explicitly in the variable list.
The throughput formula uses request_size, but the definitions list omits it. Add a bullet defining expected units (bytes) and what it represents (effective produce request payload size) to avoid ambiguity.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
`@modules/develop/pages/manage-topics/configure-producers-for-cloud-topics.adoc`
around lines 24 - 30, Add an explicit bullet for request_size to the variable
list: define request_size as the effective produce request payload size measured
in bytes (i.e., the average payload size the client sends per produce request),
and state that this is the tunable client-controlled value used in the
throughput formula alongside broker_count, max_in_flight, and latency_seconds so
there is no ambiguity about units or meaning.
Feediver1
reviewed
May 11, 2026
|
|
||
| == Producer Theoretical Throughput | ||
|
|
||
| The same principles that apply for standard topics also apply to Cloud Topics. To achieve good single-producer throughput, they become even more important. |
Contributor
There was a problem hiding this comment.
Suggested change
| The same principles that apply for standard topics also apply to Cloud Topics. To achieve good single-producer throughput, they become even more important. | |
| The same usage principles and requirements that apply for standard topics also apply to Cloud Topics. To achieve good single-producer throughput, they become even more important. |
Feediver1
reviewed
May 11, 2026
|
|
||
| That being said, another easy way to increase throughput in the system is to just increase producer count, as that will naturally increase available parallelism in the system as more connections are opened to the brokers. | ||
|
|
||
| == Producer Settings |
Contributor
There was a problem hiding this comment.
Suggested change
| == Producer Settings | |
| == Producer settings |
Feediver1
reviewed
May 11, 2026
|
|
||
| Most Kafka client libraries offer a lot of tunables, with many properties affecting request size. We can't cover all of them, but will touch on the most important ones, give an example for the Kafka Java client, and point out a few gotchas in other libraries. | ||
|
|
||
| == Batches and Requests |
Contributor
There was a problem hiding this comment.
Suggested change
| == Batches and Requests | |
| == Batches and requests |
Feediver1
reviewed
May 11, 2026
|
|
||
| A request can contain multiple batches (with exceptions as per below), and hence makes the batch size not as important from a Cloud Topics perspective. However, this requires that a producer is producing to multiple partitions and that there are enough partitions per broker to fill the request with batches. | ||
|
|
||
| == Java Client |
Contributor
There was a problem hiding this comment.
Suggested change
| == Java Client | |
| == Java client |
Feediver1
reviewed
May 11, 2026
|
|
||
| == Java Client | ||
|
|
||
| For the Java client, we recommend at least the following settings: |
Contributor
There was a problem hiding this comment.
Suggested change
| For the Java client, we recommend at least the following settings: | |
| For the Java client, Redpanda Data recommends the following as minimal settings: |
Feediver1
reviewed
May 11, 2026
|
|
||
| This page is specifically focused on client producer tuning for Cloud Topics. However, the general producer configuration guidance still applies. See xref:develop:produce-data/configure-producers.adoc[]. | ||
|
|
||
| == Producer Theoretical Throughput |
Contributor
There was a problem hiding this comment.
Suggested change
| == Producer Theoretical Throughput | |
| == Overview |
Feediver1
reviewed
May 11, 2026
|
|
||
| The same principles that apply for standard topics also apply to Cloud Topics. To achieve good single-producer throughput, they become even more important. | ||
|
|
||
| With idempotency enabled, Kafka's protocol allows only 5 in-flight requests at a time on a single broker connection. This imposes a tight limit on how much data can be in flight at a single time. Over high-latency links, this is already a problem for standard topics. With Cloud Topics, everything becomes a high-latency link due to the default 250ms batching behaviour of the broker, which reduces cloud storage costs. |
Contributor
There was a problem hiding this comment.
Suggested change
| With idempotency enabled, Kafka's protocol allows only 5 in-flight requests at a time on a single broker connection. This imposes a tight limit on how much data can be in flight at a single time. Over high-latency links, this is already a problem for standard topics. With Cloud Topics, everything becomes a high-latency link due to the default 250ms batching behaviour of the broker, which reduces cloud storage costs. | |
| With idempotency enabled, Kafka's protocol allows only five in-flight requests at a time on a single broker connection. This imposes a tight limit on how much data can be in flight at a single time. Over high-latency links, this is already a problem for standard topics. With Cloud Topics, everything becomes a high-latency link due to the default 250ms batching behavior of the broker, which reduces cloud storage costs. |
Feediver1
reviewed
May 11, 2026
|
|
||
| With idempotency enabled, Kafka's protocol allows only 5 in-flight requests at a time on a single broker connection. This imposes a tight limit on how much data can be in flight at a single time. Over high-latency links, this is already a problem for standard topics. With Cloud Topics, everything becomes a high-latency link due to the default 250ms batching behaviour of the broker, which reduces cloud storage costs. | ||
|
|
||
| The maximum throughput for a single producer can be calculated as follows: |
Contributor
There was a problem hiding this comment.
Suggested change
| The maximum throughput for a single producer can be calculated as follows: | |
| Calculate the maximum throughput for a single producer as follows: |
Feediver1
reviewed
May 11, 2026
| broker_count * max_in_flight * request_size / latency_seconds | ||
| ---- | ||
|
|
||
| with the following definitions: |
Contributor
There was a problem hiding this comment.
Suggested change
| with the following definitions: | |
| Throughput formula definitions: |
Feediver1
reviewed
May 11, 2026
| with the following definitions: | ||
|
|
||
| * `broker_count`: The number of brokers in the cluster. | ||
| * `max_in_flight`: The maximum number of in-flight requests on a single connection. With an idempotent producer, this is usually 5. |
Contributor
There was a problem hiding this comment.
Suggested change
| * `max_in_flight`: The maximum number of in-flight requests on a single connection. With an idempotent producer, this is usually 5. | |
| * `max_in_flight`: The maximum number of in-flight requests on a single connection. With an idempotent producer, this is usually five. |
Feediver1
reviewed
May 11, 2026
|
|
||
| * `broker_count`: The number of brokers in the cluster. | ||
| * `max_in_flight`: The maximum number of in-flight requests on a single connection. With an idempotent producer, this is usually 5. | ||
| * `latency_seconds`: The latency of a single produce request. Assuming normal operation, this can be equated to the 250ms as described above. In practice, it will mostly be lower, as the timer starts with the first byte arriving. |
Contributor
There was a problem hiding this comment.
Suggested change
| * `latency_seconds`: The latency of a single produce request. Assuming normal operation, this can be equated to the 250ms as described above. In practice, it will mostly be lower, as the timer starts with the first byte arriving. | |
| * `latency_seconds`: The latency of a single produce request. Assuming normal operation, this can be equated to the 250ms as earlier. In practice, it is typically lower, as the timer starts with the first byte arriving. |
Feediver1
reviewed
May 11, 2026
| * `max_in_flight`: The maximum number of in-flight requests on a single connection. With an idempotent producer, this is usually 5. | ||
| * `latency_seconds`: The latency of a single produce request. Assuming normal operation, this can be equated to the 250ms as described above. In practice, it will mostly be lower, as the timer starts with the first byte arriving. | ||
|
|
||
| Finally, we have `request_size`. This is the most important property from a tuning perspective, as it's under client control while the others are effectively constants. |
Contributor
There was a problem hiding this comment.
Suggested change
| Finally, we have `request_size`. This is the most important property from a tuning perspective, as it's under client control while the others are effectively constants. | |
| The `request_size` property is most important from a tuning perspective, because it's under client control while the other properties are effectively constants. |
Feediver1
reviewed
May 11, 2026
|
|
||
| Finally, we have `request_size`. This is the most important property from a tuning perspective, as it's under client control while the others are effectively constants. | ||
|
|
||
| That being said, another easy way to increase throughput in the system is to just increase producer count, as that will naturally increase available parallelism in the system as more connections are opened to the brokers. |
Contributor
There was a problem hiding this comment.
Suggested change
| That being said, another easy way to increase throughput in the system is to just increase producer count, as that will naturally increase available parallelism in the system as more connections are opened to the brokers. | |
| Another easy way to increase throughput in the system is to increase producer count, as doing so naturally increases available parallelism in the system as more connections are opened to the brokers. |
Feediver1
reviewed
May 11, 2026
|
|
||
| == Producer Settings | ||
|
|
||
| Most Kafka client libraries offer a lot of tunables, with many properties affecting request size. We can't cover all of them, but will touch on the most important ones, give an example for the Kafka Java client, and point out a few gotchas in other libraries. |
Contributor
There was a problem hiding this comment.
Suggested change
| Most Kafka client libraries offer a lot of tunables, with many properties affecting request size. We can't cover all of them, but will touch on the most important ones, give an example for the Kafka Java client, and point out a few gotchas in other libraries. | |
| Most Kafka client libraries offer as assortment of tunables, with many properties impacting request size. The most important ones are described here, along with an example for the Kafka Java client, as well as caveats from other libraries. |
Feediver1
reviewed
May 11, 2026
|
|
||
| A Kafka produce request consists of one or more batches. A batch contains multiple records. Records mostly correspond to application-level messages as passed to the Kafka client API. At the broker level, the unit that matters is the batch, as everything happens at the batch level. | ||
|
|
||
| As such, creating the largest possible batches is the most important factor for performance in general, and equally for Cloud Topics. |
Contributor
There was a problem hiding this comment.
Suggested change
| As such, creating the largest possible batches is the most important factor for performance in general, and equally for Cloud Topics. | |
| Hence, creating the largest possible batches is the most important factor for performance in general, and equally for Cloud Topics. |
Feediver1
reviewed
May 11, 2026
|
|
||
| As such, creating the largest possible batches is the most important factor for performance in general, and equally for Cloud Topics. | ||
|
|
||
| A request can contain multiple batches (with exceptions as per below), and hence makes the batch size not as important from a Cloud Topics perspective. However, this requires that a producer is producing to multiple partitions and that there are enough partitions per broker to fill the request with batches. |
Contributor
There was a problem hiding this comment.
Suggested change
| A request can contain multiple batches (with exceptions as per below), and hence makes the batch size not as important from a Cloud Topics perspective. However, this requires that a producer is producing to multiple partitions and that there are enough partitions per broker to fill the request with batches. | |
| A request can contain multiple batches (with exceptions as shown below), and hence makes the batch size not as important from a Cloud Topics perspective. However, this requires that a producer is producing to multiple partitions and that there are enough partitions per broker to fill the request with batches. |
Feediver1
reviewed
May 11, 2026
| | `1048576 (default)` | ||
| |=== | ||
|
|
||
| As per the above formula, with a basic three-broker setup and enough partitions, one can achieve a maximum throughput of ~65 MB/s per producer. If more throughput is needed on a single producer, it's recommended to further increase batch and max request size. |
Contributor
There was a problem hiding this comment.
Suggested change
| As per the above formula, with a basic three-broker setup and enough partitions, one can achieve a maximum throughput of ~65 MB/s per producer. If more throughput is needed on a single producer, it's recommended to further increase batch and max request size. | |
| As shown in the preceding formula, with a basic three-broker setup and enough partitions, you can achieve a maximum throughput of ~65 MB/s per producer. If more throughput is needed on a single producer, increase batch and max request size. |
Feediver1
reviewed
May 11, 2026
|
|
||
| As per the above formula, with a basic three-broker setup and enough partitions, one can achieve a maximum throughput of ~65 MB/s per producer. If more throughput is needed on a single producer, it's recommended to further increase batch and max request size. | ||
|
|
||
| Note that while it's recommended to set `linger.ms` to a higher acceptable value, it is not that important for Cloud Topics, given that as soon as there are 5 requests in flight, messages will be force batched even after crossing the `linger.ms` threshold. |
Contributor
There was a problem hiding this comment.
Suggested change
| Note that while it's recommended to set `linger.ms` to a higher acceptable value, it is not that important for Cloud Topics, given that as soon as there are 5 requests in flight, messages will be force batched even after crossing the `linger.ms` threshold. | |
| Note that while it's recommended to set `linger.ms` to a higher acceptable value, it is not so important for Cloud Topics, because as soon as there are five requests in flight, messages are force batched even after crossing the `linger.ms` threshold. |
Feediver1
reviewed
May 11, 2026
|
|
||
| == librdkafka | ||
|
|
||
| librdkafka is a commonly used Kafka C library. However, it's also the backing library for many other Kafka clients like confluent-kafka-python. |
Contributor
There was a problem hiding this comment.
Suggested change
| librdkafka is a commonly used Kafka C library. However, it's also the backing library for many other Kafka clients like confluent-kafka-python. | |
| librdkafka is a commonly-used Kafka C library. However, it's also the backing library for many other Kafka clients like confluent-kafka-python. |
Feediver1
reviewed
May 11, 2026
|
|
||
| librdkafka is a commonly used Kafka C library. However, it's also the backing library for many other Kafka clients like confluent-kafka-python. | ||
|
|
||
| Unfortunately, it has one deficiency in contrast to other Kafka client libraries in that it only allows a single batch in a produce request. This massively cuts down on how much data is packed into a single request. Hence, it's important to increase `batch.size` to even higher values, as it will effectively be the limiting factor. librdkafka uses a default of 1MB, which allows for decent throughput. |
Contributor
There was a problem hiding this comment.
Suggested change
| Unfortunately, it has one deficiency in contrast to other Kafka client libraries in that it only allows a single batch in a produce request. This massively cuts down on how much data is packed into a single request. Hence, it's important to increase `batch.size` to even higher values, as it will effectively be the limiting factor. librdkafka uses a default of 1MB, which allows for decent throughput. | |
| Note that it has a deficiency in contrast to other Kafka client libraries: it only allows a single batch in a produce request. This massively cuts down on how much data is packed into a single request. Hence, it's important to increase `batch.size` to even higher values, as it will effectively be the limiting factor. librdkafka uses a default of 1MB, which typically allows for decent throughput. |
dotnwat
reviewed
May 11, 2026
|
|
||
| As such, creating the largest possible batches is the most important factor for performance in general, and equally for Cloud Topics. | ||
|
|
||
| A request can contain multiple batches (with exceptions as per below), and hence makes the batch size not as important from a Cloud Topics perspective. However, this requires that a producer is producing to multiple partitions and that there are enough partitions per broker to fill the request with batches. |
Member
There was a problem hiding this comment.
The previous sentence was
As such, creating the largest possible batches is the most important factor for performance in general, and equally for Cloud Topics.
And now we say this
A request can contain multiple batches (with exceptions as per below), and hence makes the batch size not as important from a Cloud Topics perspective.
And these read to me as a bit contradictory?
Member
Author
There was a problem hiding this comment.
Yes you are right, they do read a bit like that. Both are true at the same time though haha. Let me try to rephrase a bit.
Member
Author
There was a problem hiding this comment.
I have rephrased it a bit.
Comment on lines
+58
to
+61
| | `131072` | ||
|
|
||
| | `max.request.size` | ||
| | `1048576 (default)` |
Member
There was a problem hiding this comment.
these feel a bit small, no? i guess these are minimums?
Member
Author
There was a problem hiding this comment.
I mean 1MB is plenty but it obviously depends on so many things which is why these blanket recommendations are hard. I don't want to go higher than needed because of the other second order effects of large requests in regards to memory reservation/starvation.
Member
There was a problem hiding this comment.
Oh I meant the 128kb size. But yeh, I'm good with whatever!
Adds a page for producer config tuning. We explain the reasoning behind single producer throughput and how it is affected by batch size etc. This allows for better reasoning across clients. Also we give some example values for the Java client and point out the deficiencies of librdkafka.
StephanDollberg
force-pushed
the
stephan/ct-properties
branch
from
e01e1ae to
81f92c3
Compare
dotnwat
approved these changes
May 12, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a page for producer config tuning.
We explain the reasoning behind single producer throughput and how it is affected by batch size etc. This allows for better reasoning across clients.
Also we give some example values for the Java client and point out the deficiencies of librdkafka.
Cloud docs PR to follow.
Description
Resolves https://redpandadata.atlassian.net/browse/
Review deadline:
Page previews
Checks