Repository: kafka Updated Branches: refs/heads/trunk 5e65c0da4 -> 21fea170d
MINOR: add upgrade section for 1.0.0 1. Add upgrade section for 1.0.0, including Streams API changes section. 2. Add metrics name changes section. Author: Guozhang Wang <wangg...@gmail.com> Reviewers: Eno Thereska <eno.there...@gmail.com>, Damian Guy <damian....@gmail.com> Closes #3687 from guozhangwang/KMinor-metrics-upgrade-guide Project: http://git-wip-us.apache.org/repos/asf/kafka/repo Commit: http://git-wip-us.apache.org/repos/asf/kafka/commit/21fea170 Tree: http://git-wip-us.apache.org/repos/asf/kafka/tree/21fea170 Diff: http://git-wip-us.apache.org/repos/asf/kafka/diff/21fea170 Branch: refs/heads/trunk Commit: 21fea170d8499a7153f2b821bcd32a55ad602645 Parents: 5e65c0d Author: Guozhang Wang <wangg...@gmail.com> Authored: Thu Aug 24 09:12:12 2017 -0700 Committer: Guozhang Wang <wangg...@gmail.com> Committed: Thu Aug 24 09:12:12 2017 -0700 ---------------------------------------------------------------------- docs/streams/upgrade-guide.html | 22 +++++++++++++++++++--- docs/upgrade.html | 12 ++++++++++-- 2 files changed, 29 insertions(+), 5 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/kafka/blob/21fea170/docs/streams/upgrade-guide.html ---------------------------------------------------------------------- diff --git a/docs/streams/upgrade-guide.html b/docs/streams/upgrade-guide.html index 7f2c9f6..bd0bb8a 100644 --- a/docs/streams/upgrade-guide.html +++ b/docs/streams/upgrade-guide.html @@ -21,15 +21,21 @@ <h1>Upgrade Guide & API Changes</h1> <p> + If you want to upgrade from 0.11.0.x to 1.0.0 you don't need to do any code changes as the public API is fully backward compatible. + However, some public APIs were deprecated and thus it is recommended to update your code eventually to allow for future upgrades. + See <a href="#streams_api_changes_100">below</a> a complete list of 1.0.0 API and semantic changes that allow you to advance your application and/or simplify your code base, including the usage of new features. + </p> + + <p> If you want to upgrade from 0.10.2.x to 0.11.0 you don't need to do any code changes as the public API is fully backward compatible. - However, some configuration parameters were deprecated and thus it is recommend to update your code eventually to allow for future upgrades. - See <a href="#streams_api_changes_0110">below</a> a complete list of 0.11.0 API and semantical changes that allow you to advance your application and/or simplify your code base, including the usage of new features. + However, some configuration parameters were deprecated and thus it is recommended to update your code eventually to allow for future upgrades. + See <a href="#streams_api_changes_0110">below</a> a complete list of 0.11.0 API and semantic changes that allow you to advance your application and/or simplify your code base, including the usage of new features. </p> <p> If you want to upgrade from 0.10.1.x to 0.10.2, see the <a href="/{{version}}/documentation/#upgrade_1020_streams"><b>Upgrade Section for 0.10.2</b></a>. It highlights incompatible changes you need to consider to upgrade your code and application. - See <a href="#streams_api_changes_0102">below</a> a complete list of 0.10.2 API and semantical changes that allow you to advance your application and/or simplify your code base, including the usage of new features. + See <a href="#streams_api_changes_0102">below</a> a complete list of 0.10.2 API and semantic changes that allow you to advance your application and/or simplify your code base, including the usage of new features. </p> <p> @@ -38,6 +44,16 @@ See <a href="#streams_api_changes_0101">below</a> a complete list of 0.10.1 API changes that allow you to advance your application and/or simplify your code base, including the usage of new features. </p> + <h3><a id="streams_api_changes_100" href="#streams_api_changes_100">Streams API changes in 1.0.0</a></h3> + <!-- TODO: KIP-120, 138, 160, 161, 167, 173 --> + + <p> + If you are monitoring on task level or processor-node / state store level Streams metrics, please note that the metrics sensor name and hierarchy was changed: + The task ids, store names and processor names are no longer in the sensor metrics names, but instead are added as tags of the sensors to achieve consistent metrics hierarchy. + As a result you may need to make corresponding code changes on your metrics reporting and monitoring tools when upgrading to 1.0.0. + Detailed metrics sensor can be found in the <a href="#kafka_streams_monitoring">Streams Monitoring</a> section. + </p> + <h3><a id="streams_api_changes_0110" href="#streams_api_changes_0110">Streams API changes in 0.11.0.0</a></h3> <p> Updates in <code>StreamsConfig</code>: </p> http://git-wip-us.apache.org/repos/asf/kafka/blob/21fea170/docs/upgrade.html ---------------------------------------------------------------------- diff --git a/docs/upgrade.html b/docs/upgrade.html index bb26c52..05e39e9 100644 --- a/docs/upgrade.html +++ b/docs/upgrade.html @@ -76,6 +76,16 @@ <li> <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-112%3A+Handle+disk+failure+for+JBOD">KIP-112</a>: FetchResponse v6 introduces error code for KafkaStorageException. </li> </ul> +<h5><a id="upgrade_100_streams" href="#upgrade_100_streams">Upgrading a 1.0.0 Kafka Streams Application</a></h5> +<ul> + <li> Upgrading your Streams application from 0.11.0 to 1.0.0 does not require a broker upgrade. + A Kafka Streams 1.0.0 application can connect to 0.11.0, 0.10.2 and 0.10.1 brokers (it is not possible to connect to 0.10.0 brokers though). </li> + <li> If you are monitoring on streams metrics, you will need make some changes to the metrics names in your reporting and monitoring code, because the metrics sensor hierarchy was changed. </li> + <li> There are a few public APIs including <code>ProcessorContext#schedule()</code>, <code>Processor#punctuate()</code> and <code>KStreamBuilder</code>, <code>TopologyBuilder</code> are being deprecated by new APIs. + We recommend making corresponding code changes, which should be very minor since the new APIs look very similary, when you upgrade. + <li> See <a href="/{{version}}/documentation/streams#streams_api_changes_100">Streams API changes in 1.0.0</a> for more details. </li> +</ul> + <h4><a id="upgrade_11_0_0" href="#upgrade_11_0_0">Upgrading from 0.8.x, 0.9.x, 0.10.0.x, 0.10.1.x or 0.10.2.x to 0.11.0.0</a></h4> <p>Kafka 0.11.0.0 introduces a new message format version as well as wire protocol changes. By following the recommended rolling upgrade plan below, you guarantee no downtime during the upgrade. However, please review the <a href="#upgrade_1100_notable">notable changes in 0.11.0.0</a> before upgrading. @@ -277,8 +287,6 @@ Kafka cluster before upgrading your clients. Version 0.10.2 brokers support 0.8. </li> </ul> - - <h5><a id="upgrade_1020_notable" href="#upgrade_1020_notable">Notable changes in 0.10.2.0</a></h5> <ul> <li>The Java clients (producer and consumer) have acquired the ability to communicate with older brokers. Version 0.10.2 clients