This is an automated email from the ASF dual-hosted git repository.
je-ik pushed a commit to branch feat/18479-kafka-streams-runner-skeleton
in repository https://gitbox.apache.org/repos/asf/beam.git
The following commit(s) were added to
refs/heads/feat/18479-kafka-streams-runner-skeleton by this push:
new 511a40e4f20 [GSoC 2026] Kafka Streams runner: separate the source's
poll size from the bundle size, and expose the session timeout (#39748)
511a40e4f20 is described below
commit 511a40e4f20739645943ab8eff69a1279591b813
Author: M Junaid Shaukat <[email protected]>
AuthorDate: Fri Aug 14 14:19:59 2026 +0500
[GSoC 2026] Kafka Streams runner: separate the source's poll size from the
bundle size, and expose the session timeout (#39748)
---
.../kafka/streams/KafkaStreamsPipelineOptions.java | 21 ++++++
.../kafka/streams/KafkaStreamsPipelineRunner.java | 14 +++-
.../kafka/streams/translation/ReadTranslator.java | 2 +-
.../KafkaStreamsPipelineRunnerConfigTest.java | 86 ++++++++++++++++++++++
4 files changed, 121 insertions(+), 2 deletions(-)
diff --git
a/runners/kafka-streams/src/main/java/org/apache/beam/runners/kafka/streams/KafkaStreamsPipelineOptions.java
b/runners/kafka-streams/src/main/java/org/apache/beam/runners/kafka/streams/KafkaStreamsPipelineOptions.java
index 44abc8e5b34..180e1ef028f 100644
---
a/runners/kafka-streams/src/main/java/org/apache/beam/runners/kafka/streams/KafkaStreamsPipelineOptions.java
+++
b/runners/kafka-streams/src/main/java/org/apache/beam/runners/kafka/streams/KafkaStreamsPipelineOptions.java
@@ -49,6 +49,27 @@ public interface KafkaStreamsPipelineOptions extends
PortablePipelineOptions {
void setMaxBundleSize(int maxBundleSize);
+ @Description(
+ "How many elements an unbounded source may yield per poll. Separate from
--maxBundleSize:"
+ + " a small bundle is how you get output promptly, while how much a
source reads at a"
+ + " time is about throughput, and tying them together means a
pipeline cannot have both.")
+ @Default.Integer(1000)
+ int getReadMaxElementsPerPoll();
+
+ void setReadMaxElementsPerPoll(int readMaxElementsPerPoll);
+
+ @Description(
+ "How long the consumer group waits before deciding an instance has gone,
in milliseconds."
+ + " This is the floor on how quickly work moves to another instance
after one is lost,"
+ + " since a departed instance is not noticed any sooner. Kafka's
default of 45s is kept,"
+ + " but a pipeline that values recovery over tolerance of a slow or
briefly paused"
+ + " instance can lower it — a broker will not accept a value below
its"
+ + " group.min.session.timeout.ms, which itself defaults to 6s.")
+ @Default.Integer(45_000)
+ int getSessionTimeoutMs();
+
+ void setSessionTimeoutMs(int sessionTimeoutMs);
+
@Description(
"Intended cap on how long a bundle may stay open, in milliseconds. NOT
APPLIED YET: closing a"
+ " bundle from a wall-clock punctuator made a pipeline with two
chained GroupByKeys"
diff --git
a/runners/kafka-streams/src/main/java/org/apache/beam/runners/kafka/streams/KafkaStreamsPipelineRunner.java
b/runners/kafka-streams/src/main/java/org/apache/beam/runners/kafka/streams/KafkaStreamsPipelineRunner.java
index de08480a61d..baa62f31aa4 100644
---
a/runners/kafka-streams/src/main/java/org/apache/beam/runners/kafka/streams/KafkaStreamsPipelineRunner.java
+++
b/runners/kafka-streams/src/main/java/org/apache/beam/runners/kafka/streams/KafkaStreamsPipelineRunner.java
@@ -26,6 +26,7 @@ import
org.apache.beam.runners.jobsubmission.PortablePipelineResult;
import org.apache.beam.runners.jobsubmission.PortablePipelineRunner;
import
org.apache.beam.runners.kafka.streams.translation.KafkaStreamsPipelineTranslator;
import
org.apache.beam.runners.kafka.streams.translation.KafkaStreamsTranslationContext;
+import org.apache.kafka.clients.consumer.ConsumerConfig;
import org.apache.kafka.streams.KafkaStreams;
import org.apache.kafka.streams.StreamsConfig;
import org.apache.kafka.streams.Topology;
@@ -162,7 +163,8 @@ public class KafkaStreamsPipelineRunner implements
PortablePipelineRunner {
}
}
- private Properties streamsConfig(JobInfo jobInfo) {
+ // Visible for testing: the session timeout and the heartbeat derived from
it.
+ Properties streamsConfig(JobInfo jobInfo) {
Properties props = new Properties();
props.put(StreamsConfig.BOOTSTRAP_SERVERS_CONFIG,
pipelineOptions.getBootstrapServers());
props.put(StreamsConfig.APPLICATION_ID_CONFIG,
pipelineOptions.getApplicationId());
@@ -177,6 +179,16 @@ public class KafkaStreamsPipelineRunner implements
PortablePipelineRunner {
// is
// what Kafka Streams does by default when no client id is set.
props.put(StreamsConfig.CLIENT_ID_CONFIG, jobInfo.jobId() + "-" +
UUID.randomUUID());
+ // How quickly a lost instance is noticed, which is the floor on how
quickly its work moves
+ // elsewhere. The heartbeat must be shorter than the timeout, or a healthy
instance would be
+ // declared dead between beats; a third is the ratio Kafka's own defaults
use. Deriving it
+ // rather than exposing it keeps the pair consistent whatever the timeout
is set to.
+ int sessionTimeoutMs = pipelineOptions.getSessionTimeoutMs();
+ props.put(
+
StreamsConfig.consumerPrefix(ConsumerConfig.SESSION_TIMEOUT_MS_CONFIG),
sessionTimeoutMs);
+ props.put(
+
StreamsConfig.consumerPrefix(ConsumerConfig.HEARTBEAT_INTERVAL_MS_CONFIG),
+ Math.max(1, sessionTimeoutMs / 3));
return props;
}
}
diff --git
a/runners/kafka-streams/src/main/java/org/apache/beam/runners/kafka/streams/translation/ReadTranslator.java
b/runners/kafka-streams/src/main/java/org/apache/beam/runners/kafka/streams/translation/ReadTranslator.java
index 69006661ee6..b6620203b2d 100644
---
a/runners/kafka-streams/src/main/java/org/apache/beam/runners/kafka/streams/translation/ReadTranslator.java
+++
b/runners/kafka-streams/src/main/java/org/apache/beam/runners/kafka/streams/translation/ReadTranslator.java
@@ -136,7 +136,7 @@ class ReadTranslator implements PTransformTranslator {
// splitting a source that has already been split.
UnboundedSource<T, CheckpointT> readableSource = singleSplitOf(source,
context);
Coder<CheckpointT> checkpointCoder =
readableSource.getCheckpointMarkCoder();
- int maxElementsPerPoll = context.getPipelineOptions().getMaxBundleSize();
+ int maxElementsPerPoll =
context.getPipelineOptions().getReadMaxElementsPerPoll();
int checkpointEveryNPolls =
context.getPipelineOptions().getReadCheckpointNumBundles();
topology.addSource(
diff --git
a/runners/kafka-streams/src/test/java/org/apache/beam/runners/kafka/streams/KafkaStreamsPipelineRunnerConfigTest.java
b/runners/kafka-streams/src/test/java/org/apache/beam/runners/kafka/streams/KafkaStreamsPipelineRunnerConfigTest.java
new file mode 100644
index 00000000000..c98d50c75a0
--- /dev/null
+++
b/runners/kafka-streams/src/test/java/org/apache/beam/runners/kafka/streams/KafkaStreamsPipelineRunnerConfigTest.java
@@ -0,0 +1,86 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.beam.runners.kafka.streams;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.is;
+import static org.hamcrest.Matchers.lessThan;
+
+import java.util.Properties;
+import org.apache.beam.runners.fnexecution.provisioning.JobInfo;
+import org.apache.beam.sdk.options.PipelineOptionsFactory;
+import org.apache.beam.sdk.util.construction.PipelineOptionsTranslation;
+import org.apache.kafka.clients.consumer.ConsumerConfig;
+import org.apache.kafka.streams.StreamsConfig;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Tests for the Kafka Streams configuration the runner builds from its
pipeline options. */
+@RunWith(JUnit4.class)
+public class KafkaStreamsPipelineRunnerConfigTest {
+
+ private static final String SESSION_TIMEOUT =
+ StreamsConfig.consumerPrefix(ConsumerConfig.SESSION_TIMEOUT_MS_CONFIG);
+ private static final String HEARTBEAT =
+
StreamsConfig.consumerPrefix(ConsumerConfig.HEARTBEAT_INTERVAL_MS_CONFIG);
+
+ private static Properties configFor(Integer sessionTimeoutMs) {
+ KafkaStreamsPipelineOptions options =
+ PipelineOptionsFactory.create().as(KafkaStreamsPipelineOptions.class);
+ options.setApplicationId("an-application");
+ options.setBootstrapServers("localhost:9092");
+ if (sessionTimeoutMs != null) {
+ options.setSessionTimeoutMs(sessionTimeoutMs);
+ }
+ JobInfo jobInfo =
+ JobInfo.create("a-job", "a-job", "",
PipelineOptionsTranslation.toProto(options));
+ return new KafkaStreamsPipelineRunner(options).streamsConfig(jobInfo);
+ }
+
+ @Test
+ public void theSessionTimeoutDefaultsToKafkasOwn() {
+ // Changing this would change how long a lost instance goes unnoticed, so
it is deliberate that
+ // the runner keeps Kafka's default rather than choosing its own.
+ assertThat(configFor(null).get(SESSION_TIMEOUT), is(45_000));
+ }
+
+ @Test
+ public void theSessionTimeoutIsWhateverThePipelineAskedFor() {
+ assertThat(configFor(6_000).get(SESSION_TIMEOUT), is(6_000));
+ }
+
+ @Test
+ public void theHeartbeatIsAThirdOfTheSessionTimeout() {
+ assertThat(configFor(6_000).get(HEARTBEAT), is(2_000));
+ }
+
+ @Test
+ public void theHeartbeatStaysShorterThanEvenATinySessionTimeout() {
+ // Kafka rejects a heartbeat that is not shorter than the session timeout,
so deriving it has
+ // to hold for small values too — a fixed floor would not. One millisecond
is excluded because
+ // no positive heartbeat is shorter than it, and a broker would refuse
such a timeout anyway.
+ for (int sessionTimeoutMs : new int[] {2, 10, 100, 200, 1_000, 6_000,
45_000}) {
+ Properties config = configFor(sessionTimeoutMs);
+ assertThat(
+ "heartbeat must stay under the session timeout for " +
sessionTimeoutMs + "ms",
+ (Integer) config.get(HEARTBEAT),
+ lessThan((Integer) config.get(SESSION_TIMEOUT)));
+ }
+ }
+}
