cadonna commented on a change in pull request #9969:
URL: https://github.com/apache/kafka/pull/9969#discussion_r565930820
##########
File path: docs/streams/architecture.html
##########
@@ -110,6 +110,11 @@ <h3 class="anchor-heading"><a
id="streams_architecture_threads" class="anchor-li
and Kafka Streams takes care of distributing partitions amongst tasks
that run in the application instances. You can start as many threads of the
application
as there are input Kafka topic partitions so that, across all running
instances of an application, every thread (or rather, the tasks it runs) has at
least one input partition to process.
</p>
+ <p>
+ As of Kafka 2.8 you may scale clients much in the same way you can
scale your application.
+ Simply add or remove threads and Kafka Streams will take care of
redistributing the partitions.
+ You may also add threads to replace threads that have died removing
the need to restart clients to recover the number of thread running.
Review comment:
Also here, I would use `stream threads`.
##########
File path: docs/streams/architecture.html
##########
@@ -110,6 +110,11 @@ <h3 class="anchor-heading"><a
id="streams_architecture_threads" class="anchor-li
and Kafka Streams takes care of distributing partitions amongst tasks
that run in the application instances. You can start as many threads of the
application
as there are input Kafka topic partitions so that, across all running
instances of an application, every thread (or rather, the tasks it runs) has at
least one input partition to process.
</p>
+ <p>
+ As of Kafka 2.8 you may scale clients much in the same way you can
scale your application.
Review comment:
Shouldn't we use `stream threads` instead of `clients` here? We are
actually scaling stream threads. It just happens to be that each stream thread
has its own clients. This might change in future.
##########
File path: docs/streams/upgrade-guide.html
##########
@@ -91,6 +91,29 @@ <h3><a id="streams_api_changes_280"
href="#streams_api_changes_280">Streams API
We extended <code>StreamJoined</code> to include the options
<code>withLoggingEnabled()</code> and <code>withLoggingDisabled()</code> in
<a
href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-689%3A+Extend+%60StreamJoined%60+to+allow+more+store+configs";>KIP-689</a>.
</p>
+ <p>
+ We added two new methods to Kafka Streams, namely
<code>addStreamThread()</code> and <code>removeStreamThread()</code> in
+ <a href="https://cwiki.apache.org/confluence/x/FDd4CQ";>KIP-663</a>.
+ These enabled adding a removing StreamThreads to running KafkaStreams
client.
+ </p>
+ <p>
+ We deprecated <code>setUncaughtExceptionHandler(final
Thread.UncaughtExceptionHandler uncaughtExceptionHandler)</code>
+ in favor of <code>setUncaughtExceptionHandler(final
StreamsUncaughtExceptionHandler streamsUncaughtExceptionHandler)</code>
+ in <a href="https://cwiki.apache.org/confluence/x/lkN4CQ";>KIP-671</a>.
+ The default handler will close the client and the client will transit
to state ERROR.
+ If you implement a custom handler, the new interface allows you to
return a <code>StreamThreadExceptionResponse</code>,
+ which will determine how the application will respond to a thread
failure.
+ </p>
+ <p>
+ Changes in <a
href="https://cwiki.apache.org/confluence/x/FDd4CQ";>KIP-663</a> necessitated
the KafkaStreams client
+ state machine to update, which was done in <a
href="https://cwiki.apache.org/confluence/x/lCvZCQ";>KIP-696</a>..
+ The ERROR state is now terminal with PENDING_ERROR being a
transitional state where the resources are closing.
+ The ERROR state indicates that there is something wrong and the
KafkaStreams clinet should not be blindly
+ restarted without classifying the error that caused the thread to fail.
+ If the error is of a type that you would like to retry, you should
have the
+ <code>StreamsUncaughtExceptionHandler</code> return
<code>REPLACE_THREAD</code>.
+ When all thread are dead there is not automatic transition to ERROR as
a new thread can be added.
Review comment:
```suggestion
When all stream threads are dead there is no automatic transition to
ERROR as a new stream thread can be added.
```
##########
File path: docs/streams/upgrade-guide.html
##########
@@ -91,6 +91,29 @@ <h3><a id="streams_api_changes_280"
href="#streams_api_changes_280">Streams API
We extended <code>StreamJoined</code> to include the options
<code>withLoggingEnabled()</code> and <code>withLoggingDisabled()</code> in
<a
href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-689%3A+Extend+%60StreamJoined%60+to+allow+more+store+configs";>KIP-689</a>.
</p>
+ <p>
+ We added two new methods to Kafka Streams, namely
<code>addStreamThread()</code> and <code>removeStreamThread()</code> in
+ <a href="https://cwiki.apache.org/confluence/x/FDd4CQ";>KIP-663</a>.
+ These enabled adding a removing StreamThreads to running KafkaStreams
client.
+ </p>
+ <p>
+ We deprecated <code>setUncaughtExceptionHandler(final
Thread.UncaughtExceptionHandler uncaughtExceptionHandler)</code>
+ in favor of <code>setUncaughtExceptionHandler(final
StreamsUncaughtExceptionHandler streamsUncaughtExceptionHandler)</code>
+ in <a href="https://cwiki.apache.org/confluence/x/lkN4CQ";>KIP-671</a>.
+ The default handler will close the client and the client will transit
to state ERROR.
+ If you implement a custom handler, the new interface allows you to
return a <code>StreamThreadExceptionResponse</code>,
+ which will determine how the application will respond to a thread
failure.
Review comment:
```suggestion
which will determine how the application will respond to a stream
thread failure.
```
##########
File path: docs/streams/upgrade-guide.html
##########
@@ -91,6 +91,29 @@ <h3><a id="streams_api_changes_280"
href="#streams_api_changes_280">Streams API
We extended <code>StreamJoined</code> to include the options
<code>withLoggingEnabled()</code> and <code>withLoggingDisabled()</code> in
<a
href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-689%3A+Extend+%60StreamJoined%60+to+allow+more+store+configs";>KIP-689</a>.
</p>
+ <p>
+ We added two new methods to Kafka Streams, namely
<code>addStreamThread()</code> and <code>removeStreamThread()</code> in
+ <a href="https://cwiki.apache.org/confluence/x/FDd4CQ";>KIP-663</a>.
+ These enabled adding a removing StreamThreads to running KafkaStreams
client.
Review comment:
Could you please revisit this sentence since it contains multiple issues?
##########
File path: docs/streams/upgrade-guide.html
##########
@@ -91,6 +91,29 @@ <h3><a id="streams_api_changes_280"
href="#streams_api_changes_280">Streams API
We extended <code>StreamJoined</code> to include the options
<code>withLoggingEnabled()</code> and <code>withLoggingDisabled()</code> in
<a
href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-689%3A+Extend+%60StreamJoined%60+to+allow+more+store+configs";>KIP-689</a>.
</p>
+ <p>
+ We added two new methods to Kafka Streams, namely
<code>addStreamThread()</code> and <code>removeStreamThread()</code> in
+ <a href="https://cwiki.apache.org/confluence/x/FDd4CQ";>KIP-663</a>.
+ These enabled adding a removing StreamThreads to running KafkaStreams
client.
+ </p>
+ <p>
+ We deprecated <code>setUncaughtExceptionHandler(final
Thread.UncaughtExceptionHandler uncaughtExceptionHandler)</code>
+ in favor of <code>setUncaughtExceptionHandler(final
StreamsUncaughtExceptionHandler streamsUncaughtExceptionHandler)</code>
+ in <a href="https://cwiki.apache.org/confluence/x/lkN4CQ";>KIP-671</a>.
+ The default handler will close the client and the client will transit
to state ERROR.
+ If you implement a custom handler, the new interface allows you to
return a <code>StreamThreadExceptionResponse</code>,
+ which will determine how the application will respond to a thread
failure.
+ </p>
+ <p>
+ Changes in <a
href="https://cwiki.apache.org/confluence/x/FDd4CQ";>KIP-663</a> necessitated
the KafkaStreams client
+ state machine to update, which was done in <a
href="https://cwiki.apache.org/confluence/x/lCvZCQ";>KIP-696</a>..
+ The ERROR state is now terminal with PENDING_ERROR being a
transitional state where the resources are closing.
+ The ERROR state indicates that there is something wrong and the
KafkaStreams clinet should not be blindly
Review comment:
```suggestion
The ERROR state indicates that there is something wrong and the
Kafka Streams client should not be blindly
```
##########
File path: docs/streams/upgrade-guide.html
##########
@@ -91,6 +91,29 @@ <h3><a id="streams_api_changes_280"
href="#streams_api_changes_280">Streams API
We extended <code>StreamJoined</code> to include the options
<code>withLoggingEnabled()</code> and <code>withLoggingDisabled()</code> in
<a
href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-689%3A+Extend+%60StreamJoined%60+to+allow+more+store+configs";>KIP-689</a>.
</p>
+ <p>
+ We added two new methods to Kafka Streams, namely
<code>addStreamThread()</code> and <code>removeStreamThread()</code> in
+ <a href="https://cwiki.apache.org/confluence/x/FDd4CQ";>KIP-663</a>.
+ These enabled adding a removing StreamThreads to running KafkaStreams
client.
+ </p>
+ <p>
+ We deprecated <code>setUncaughtExceptionHandler(final
Thread.UncaughtExceptionHandler uncaughtExceptionHandler)</code>
+ in favor of <code>setUncaughtExceptionHandler(final
StreamsUncaughtExceptionHandler streamsUncaughtExceptionHandler)</code>
+ in <a href="https://cwiki.apache.org/confluence/x/lkN4CQ";>KIP-671</a>.
+ The default handler will close the client and the client will transit
to state ERROR.
+ If you implement a custom handler, the new interface allows you to
return a <code>StreamThreadExceptionResponse</code>,
+ which will determine how the application will respond to a thread
failure.
+ </p>
+ <p>
+ Changes in <a
href="https://cwiki.apache.org/confluence/x/FDd4CQ";>KIP-663</a> necessitated
the KafkaStreams client
+ state machine to update, which was done in <a
href="https://cwiki.apache.org/confluence/x/lCvZCQ";>KIP-696</a>..
Review comment:
```suggestion
state machine to update, which was done in <a
href="https://cwiki.apache.org/confluence/x/lCvZCQ";>KIP-696</a>.
```
##########
File path: docs/streams/upgrade-guide.html
##########
@@ -91,6 +91,29 @@ <h3><a id="streams_api_changes_280"
href="#streams_api_changes_280">Streams API
We extended <code>StreamJoined</code> to include the options
<code>withLoggingEnabled()</code> and <code>withLoggingDisabled()</code> in
<a
href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-689%3A+Extend+%60StreamJoined%60+to+allow+more+store+configs";>KIP-689</a>.
</p>
+ <p>
+ We added two new methods to Kafka Streams, namely
<code>addStreamThread()</code> and <code>removeStreamThread()</code> in
Review comment:
```suggestion
We added two new methods to <code>KafkaStreams</code>, namely
<code>addStreamThread()</code> and <code>removeStreamThread()</code> in
```
##########
File path: docs/streams/architecture.html
##########
@@ -110,6 +110,11 @@ <h3 class="anchor-heading"><a
id="streams_architecture_threads" class="anchor-li
and Kafka Streams takes care of distributing partitions amongst tasks
that run in the application instances. You can start as many threads of the
application
as there are input Kafka topic partitions so that, across all running
instances of an application, every thread (or rather, the tasks it runs) has at
least one input partition to process.
</p>
+ <p>
+ As of Kafka 2.8 you may scale clients much in the same way you can
scale your application.
+ Simply add or remove threads and Kafka Streams will take care of
redistributing the partitions.
Review comment:
I would also use `stream threads` here to be more specific.
##########
File path: docs/streams/upgrade-guide.html
##########
@@ -91,6 +91,29 @@ <h3><a id="streams_api_changes_280"
href="#streams_api_changes_280">Streams API
We extended <code>StreamJoined</code> to include the options
<code>withLoggingEnabled()</code> and <code>withLoggingDisabled()</code> in
<a
href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-689%3A+Extend+%60StreamJoined%60+to+allow+more+store+configs";>KIP-689</a>.
</p>
+ <p>
+ We added two new methods to Kafka Streams, namely
<code>addStreamThread()</code> and <code>removeStreamThread()</code> in
+ <a href="https://cwiki.apache.org/confluence/x/FDd4CQ";>KIP-663</a>.
+ These enabled adding a removing StreamThreads to running KafkaStreams
client.
+ </p>
+ <p>
+ We deprecated <code>setUncaughtExceptionHandler(final
Thread.UncaughtExceptionHandler uncaughtExceptionHandler)</code>
Review comment:
```suggestion
We deprecated <code>KafkaStreams#setUncaughtExceptionHandler(final
Thread.UncaughtExceptionHandler uncaughtExceptionHandler)</code>
```
##########
File path: docs/streams/upgrade-guide.html
##########
@@ -91,6 +91,29 @@ <h3><a id="streams_api_changes_280"
href="#streams_api_changes_280">Streams API
We extended <code>StreamJoined</code> to include the options
<code>withLoggingEnabled()</code> and <code>withLoggingDisabled()</code> in
<a
href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-689%3A+Extend+%60StreamJoined%60+to+allow+more+store+configs";>KIP-689</a>.
</p>
+ <p>
+ We added two new methods to Kafka Streams, namely
<code>addStreamThread()</code> and <code>removeStreamThread()</code> in
+ <a href="https://cwiki.apache.org/confluence/x/FDd4CQ";>KIP-663</a>.
+ These enabled adding a removing StreamThreads to running KafkaStreams
client.
+ </p>
+ <p>
+ We deprecated <code>setUncaughtExceptionHandler(final
Thread.UncaughtExceptionHandler uncaughtExceptionHandler)</code>
+ in favor of <code>setUncaughtExceptionHandler(final
StreamsUncaughtExceptionHandler streamsUncaughtExceptionHandler)</code>
+ in <a href="https://cwiki.apache.org/confluence/x/lkN4CQ";>KIP-671</a>.
+ The default handler will close the client and the client will transit
to state ERROR.
Review comment:
```suggestion
The default handler will close the Kafka Streams client and the
client will transit to state ERROR.
```
##########
File path: docs/streams/upgrade-guide.html
##########
@@ -91,6 +91,29 @@ <h3><a id="streams_api_changes_280"
href="#streams_api_changes_280">Streams API
We extended <code>StreamJoined</code> to include the options
<code>withLoggingEnabled()</code> and <code>withLoggingDisabled()</code> in
<a
href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-689%3A+Extend+%60StreamJoined%60+to+allow+more+store+configs";>KIP-689</a>.
</p>
+ <p>
+ We added two new methods to Kafka Streams, namely
<code>addStreamThread()</code> and <code>removeStreamThread()</code> in
+ <a href="https://cwiki.apache.org/confluence/x/FDd4CQ";>KIP-663</a>.
+ These enabled adding a removing StreamThreads to running KafkaStreams
client.
+ </p>
+ <p>
+ We deprecated <code>setUncaughtExceptionHandler(final
Thread.UncaughtExceptionHandler uncaughtExceptionHandler)</code>
+ in favor of <code>setUncaughtExceptionHandler(final
StreamsUncaughtExceptionHandler streamsUncaughtExceptionHandler)</code>
Review comment:
```suggestion
in favor of <code>KafkaStreams#setUncaughtExceptionHandler(final
StreamsUncaughtExceptionHandler streamsUncaughtExceptionHandler)</code>
```
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
