You are viewing a plain text version of this content. The canonical link for it is here.
Posted to jira@kafka.apache.org by "mjsax (via GitHub)" <gi...@apache.org> on 2024/12/06 22:47:06 UTC
[PR] MINOR: improve Kafka Streams config docs [kafka]
mjsax opened a new pull request, #18087:
URL: https://github.com/apache/kafka/pull/18087
(no comment)
--
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.
To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MINOR: improve Kafka Streams config docs [kafka]
Posted by "mjsax (via GitHub)" <gi...@apache.org>.
mjsax commented on code in PR #18087:
URL: https://github.com/apache/kafka/pull/18087#discussion_r1874113897
##########
docs/streams/developer-guide/config-streams.html:
##########
@@ -416,68 +417,91 @@ <h4><a class="toc-backref" href="#id23">num.standby.replicas</a><a class="header
<tr class="row-even"><td>poll.ms</td>
<td>Low</td>
<td colspan="2">The amount of time in milliseconds to block waiting for input.</td>
- <td>100 milliseconds</td>
+ <td><code class="docutils literal"><span class="pre">100</span></code></td>
</tr>
- <tr class="row-odd"><td>rack.aware.assignment.tags</td>
- <td>Medium</td>
+ <tr class="row-odd"><td>rack.aware.assignment.strategy</td>
Review Comment:
Adding missing parameters.
Also update importance level to LOW. (not sure why this should be MEDIUM)
--
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.
To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MINOR: improve Kafka Streams config docs [kafka]
Posted by "mjsax (via GitHub)" <gi...@apache.org>.
mjsax commented on code in PR #18087:
URL: https://github.com/apache/kafka/pull/18087#discussion_r1874111595
##########
docs/streams/developer-guide/config-streams.html:
##########
@@ -231,9 +231,9 @@ <h4><a class="toc-backref" href="#id23">num.standby.replicas</a><a class="header
<p>Here are the optional <a href="/{{version}}/javadoc/org/apache/kafka/streams/StreamsConfig.html">Streams</a> javadocs, sorted by level of importance:</p>
<blockquote>
<div><ul class="simple">
- <li>High: These parameters can have a significant impact on performance. Take care when deciding the values of these parameters.</li>
- <li>Medium: These parameters can have some impact on performance. Your specific environment will determine how much tuning effort should be focused on these parameters.</li>
- <li>Low: These parameters have a less general or less significant impact on performance.</li>
+ <li>High: These are parameters with default value which are most likely not a good fit for production use. It's highly recommended to revisit these parameters for production usage.</li>
+ <li>Medium: The default values of these parameters should work for production for many cases, but it's not uncommon that they are changed, for example to tune performance.</li>
+ <li>Low: It should be rarely necessary to change the default for these parameters. It's only recommended to change them if there is a very specific issue you want to address.</li>
Review Comment:
Many configs have nothing to do with performance. Trying to make the level description more useful / actionable to users.
--
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.
To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MINOR: improve Kafka Streams config docs [kafka]
Posted by "mjsax (via GitHub)" <gi...@apache.org>.
mjsax commented on code in PR #18087:
URL: https://github.com/apache/kafka/pull/18087#discussion_r1874112001
##########
docs/streams/developer-guide/config-streams.html:
##########
@@ -265,12 +265,12 @@ <h4><a class="toc-backref" href="#id23">num.standby.replicas</a><a class="header
<tr class="row-odd"><td>statestore.cache.max.bytes</td>
<td>Medium</td>
<td colspan="2">Maximum number of memory bytes to be used for record caches across all threads.</td>
- <td>10485760</td>
+ <td><code class="docutils literal"><span class="pre">10485760</span></code></td>
</tr>
<tr class="row-even"><td>cache.max.bytes.buffering (Deprecated. Use statestore.cache.max.bytes instead.)</td>
<td>Medium</td>
<td colspan="2">Maximum number of memory bytes to be used for record caches across all threads.</td>
- <td>10485760 bytes</td>
+ <td><code class="docutils literal"><span class="pre">10485760</span></code></td>
Review Comment:
also remove `bytes` as the unit is already clear.
--
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.
To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MINOR: improve Kafka Streams config docs [kafka]
Posted by "mjsax (via GitHub)" <gi...@apache.org>.
mjsax merged PR #18087:
URL: https://github.com/apache/kafka/pull/18087
--
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.
To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MINOR: improve Kafka Streams config docs [kafka]
Posted by "mjsax (via GitHub)" <gi...@apache.org>.
mjsax commented on code in PR #18087:
URL: https://github.com/apache/kafka/pull/18087#discussion_r1874111813
##########
docs/streams/developer-guide/config-streams.html:
##########
@@ -265,12 +265,12 @@ <h4><a class="toc-backref" href="#id23">num.standby.replicas</a><a class="header
<tr class="row-odd"><td>statestore.cache.max.bytes</td>
<td>Medium</td>
<td colspan="2">Maximum number of memory bytes to be used for record caches across all threads.</td>
- <td>10485760</td>
+ <td><code class="docutils literal"><span class="pre">10485760</span></code></td>
Review Comment:
html cleanup (more of the same below)
--
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.
To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MINOR: improve Kafka Streams config docs [kafka]
Posted by "mjsax (via GitHub)" <gi...@apache.org>.
mjsax commented on code in PR #18087:
URL: https://github.com/apache/kafka/pull/18087#discussion_r1874112266
##########
docs/streams/developer-guide/config-streams.html:
##########
@@ -301,8 +301,9 @@ <h4><a class="toc-backref" href="#id23">num.standby.replicas</a><a class="header
</tr>
<tr class="row-even"><td>default.timestamp.extractor</td>
<td>Medium</td>
- <td colspan="2">Timestamp extractor class that implements the <code class="docutils literal"><span class="pre">TimestampExtractor</span></code> interface.</td>
- <td>See <a class="reference internal" href="#streams-developer-guide-timestamp-extractor"><span class="std std-ref">Timestamp Extractor</span></a></td>
+ <td colspan="2">Timestamp extractor class that implements the <code class="docutils literal"><span class="pre">TimestampExtractor</span></code> interface.
+ See <a class="reference internal" href="#streams-developer-guide-timestamp-extractor"><span class="std std-ref">Timestamp Extractor</span></a></td>
+ <td><code class="docutils literal"><span class="pre">FailOnInvalidTimestamp</span></code></td>
Review Comment:
move link to more doc into description and add actual default value...
--
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.
To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MINOR: improve Kafka Streams config docs [kafka]
Posted by "ableegoldman (via GitHub)" <gi...@apache.org>.
ableegoldman commented on code in PR #18087:
URL: https://github.com/apache/kafka/pull/18087#discussion_r1879254935
##########
docs/streams/developer-guide/config-streams.html:
##########
@@ -231,9 +231,9 @@ <h4><a class="toc-backref" href="#id23">num.standby.replicas</a><a class="header
<p>Here are the optional <a href="/{{version}}/javadoc/org/apache/kafka/streams/StreamsConfig.html">Streams</a> javadocs, sorted by level of importance:</p>
<blockquote>
<div><ul class="simple">
- <li>High: These parameters can have a significant impact on performance. Take care when deciding the values of these parameters.</li>
- <li>Medium: These parameters can have some impact on performance. Your specific environment will determine how much tuning effort should be focused on these parameters.</li>
- <li>Low: These parameters have a less general or less significant impact on performance.</li>
+ <li>High: These are parameters with default value which are most likely not a good fit for production use. It's highly recommended to revisit these parameters for production usage.</li>
+ <li>Medium: The default values of these parameters should work for production for many cases, but it's not uncommon that they are changed, for example to tune performance.</li>
+ <li>Low: It should be rarely necessary to change the default for these parameters. It's only recommended to change them if there is a very specific issue you want to address.</li>
Review Comment:
```suggestion
<li>Low: It should rarely be necessary to change the value for these parameters. It's only recommended to change them if there is a very specific issue you want to address.</li>
```
##########
docs/streams/developer-guide/config-streams.html:
##########
@@ -231,9 +231,9 @@ <h4><a class="toc-backref" href="#id23">num.standby.replicas</a><a class="header
<p>Here are the optional <a href="/{{version}}/javadoc/org/apache/kafka/streams/StreamsConfig.html">Streams</a> javadocs, sorted by level of importance:</p>
<blockquote>
<div><ul class="simple">
- <li>High: These parameters can have a significant impact on performance. Take care when deciding the values of these parameters.</li>
- <li>Medium: These parameters can have some impact on performance. Your specific environment will determine how much tuning effort should be focused on these parameters.</li>
- <li>Low: These parameters have a less general or less significant impact on performance.</li>
+ <li>High: These are parameters with default value which are most likely not a good fit for production use. It's highly recommended to revisit these parameters for production usage.</li>
Review Comment:
nit: grammar
```suggestion
<li>High: These are parameters with a default value which is most likely not a good fit for production use. It's highly recommended to revisit these parameters for production usage.</li>
```
--
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.
To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MINOR: improve Kafka Streams config docs [kafka]
Posted by "mjsax (via GitHub)" <gi...@apache.org>.
mjsax commented on code in PR #18087:
URL: https://github.com/apache/kafka/pull/18087#discussion_r1874114332
##########
streams/src/main/java/org/apache/kafka/streams/StreamsConfig.java:
##########
@@ -974,28 +974,6 @@ public class StreamsConfig extends AbstractConfig {
DefaultProductionExceptionHandler.class.getName(),
Importance.MEDIUM,
PRODUCTION_EXCEPTION_HANDLER_CLASS_DOC)
- .define(RACK_AWARE_ASSIGNMENT_NON_OVERLAP_COST_CONFIG,
Review Comment:
These configs should be LOW (updating and moving them to LOW-section)
--
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.
To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MINOR: improve Kafka Streams config docs [kafka]
Posted by "mjsax (via GitHub)" <gi...@apache.org>.
mjsax commented on code in PR #18087:
URL: https://github.com/apache/kafka/pull/18087#discussion_r1874113374
##########
docs/streams/developer-guide/config-streams.html:
##########
@@ -403,10 +404,10 @@ <h4><a class="toc-backref" href="#id23">num.standby.replicas</a><a class="header
</tr>
<tr class="row-even"><td>processing.guarantee</td>
<td>Medium</td>
- <td colspan="2">The processing mode. Can be either <code class="docutils literal"><span class="pre">"at_least_once"</span></code> (default)
- or <code class="docutils literal"><span class="pre">"exactly_once_v2"</span></code> (for EOS version 2, requires broker version 2.5+). Deprecated config options are
- <code class="docutils literal"><span class="pre">"exactly_once"</span></code> (for EOS version 1) and <code class="docutils literal"><span class="pre">"exactly_once_beta"</span></code> (for EOS version 2, requires broker version 2.5+)</td>.
- <td>See <a class="reference internal" href="#streams-developer-guide-processing-guarantee"><span class="std std-ref">Processing Guarantee</span></a></td>
Review Comment:
"exactly_once" and "exactly_once_beta are removed. Cleanup to not have them in the docs any longer.
--
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.
To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MINOR: improve Kafka Streams config docs [kafka]
Posted by "mjsax (via GitHub)" <gi...@apache.org>.
mjsax commented on code in PR #18087:
URL: https://github.com/apache/kafka/pull/18087#discussion_r1874091117
##########
docs/streams/developer-guide/config-streams.html:
##########
@@ -432,7 +432,7 @@ <h4><a class="toc-backref" href="#id23">num.standby.replicas</a><a class="header
<td><code class="docutils literal"><span class="pre">-1</span></code></td>
</tr>
<tr class="row-odd"><td>retry.backoff.ms</td>
- <td>Medium</td>
+ <td>Low</td>
Review Comment:
This is incorrectly documented. Level is LOW in `StreamsConfig`.
--
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.
To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] MINOR: improve Kafka Streams config docs [kafka]
Posted by "mjsax (via GitHub)" <gi...@apache.org>.
mjsax commented on PR #18087:
URL: https://github.com/apache/kafka/pull/18087#issuecomment-2547112422
Merged to `trunk` and cherry-picked to `4.0` branch.
--
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.
To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org