MINOR: Specify 2.1 as the minimum broker version for clients #19250
Conversation
ijuma
force-pushed
the
consumer-javadoc-minimum-broker-version
branch
from
a02e97c to
4c1055e
Compare
| * certain features. For example, 0.10.0 brokers do not support offsetsForTimes, because this feature was added | ||
| * in version 0.10.1. You will receive an {@link org.apache.kafka.common.errors.UnsupportedVersionException} | ||
| * This client can communicate with brokers that are version 2.1 or newer. Older or newer brokers may not support | ||
| * certain features. For example, 3.9 brokers do not support {@code subscribe(SubscriptionPattern)}, because this feature was added |
There was a problem hiding this comment.
yes, it's accurate. That feature was the last one added as part of KIP-848 (in 4.0).
| * By default a buffer is available to send immediately even if there is additional unused space in the buffer. However if you | ||
| * want to reduce the number of requests you can set <code>linger.ms</code> to something greater than 0. This will | ||
| * instruct the producer to wait up to that number of milliseconds before sending a request in hope that more records will | ||
| * By default, a buffer is available to send after a short delay even if there is additional unused space in the buffer. |
There was a problem hiding this comment.
The linger.ms default changed in 4.0.
| * then it is recommended to shut down the producer and check the contents of the last produced message to ensure that | ||
| * it is not duplicated. Finally, the producer can only guarantee idempotence for messages sent within a single session. | ||
| * To ensure idempotence, it is imperative to avoid application level re-sends since these cannot be de-duplicated. | ||
| * To achieve this, it is recommended to set {@code delivery.timeout.ms} such that retries are handled for the desired |
There was a problem hiding this comment.
We updated a different part of the javadoc to emphasize delivery.timeout.ms, but forgot to update this part.
| * <code>UnsupportedVersionException</code> when invoking an API that is not available in the running broker version. | ||
| * This client can communicate with brokers that are version 2.1 or newer. Older brokers may not support | ||
| * certain client features. For instance, {@code sendOffsetsToTransaction} with all consumer group metadata needs broker | ||
| * versions 2.5 or later. You will receive an <code>UnsupportedVersionException</code> when invoking an API that is not |
There was a problem hiding this comment.
I was a little confused by this at first, so I did some digging.
This message is due to the change in the signature of sendOffsetsToTransaction requiring ConsumerGroupMetadata groupMetadata rather than String consumerGroupId (KIP introducing the concept here, and old method signature deprecated in this commit)
But yes, this is correct. 👍
There was a problem hiding this comment.
We could just remove the "with all consumer group metadata" comment, since this is the only remaining version of the method. (I guess you can't add offsets to transactions if you are running 2.4 or older)
There was a problem hiding this comment.
Interesting, not sure if this implication was fully understood. I'll check what other updates are required due to this.
There was a problem hiding this comment.
Yeah, I don't think it was when it was deprecated.
| @@ -636,8 +632,6 @@ private TransactionManager configureTransactionState(ProducerConfig config, | |||
| * initialized, this method should no longer be used. | |||
| * | |||
| * @throws IllegalStateException if no {@code transactional.id} has been configured | |||
| * @throws org.apache.kafka.common.errors.UnsupportedVersionException fatal error indicating the broker | |||
There was a problem hiding this comment.
@jolshan Thoughts on this and similar changes? Two other options:
- Keep
UnsupportedVersionExceptionwith a generic message (instead of the specific "does not support transactions"). - Keep
UnsupportedVersionExceptionwith a different specific message.
Perhaps alternative 1 is the right approach if we expect to evolve things such that passing certain parameters may result in UnsupportedVersionException. Similar to sendOffsetsToTransaction with all consumer group metadata.
There was a problem hiding this comment.
Yeah I think 1 makes sense to leave a possibility for a more specific error than KafkaException.
When we complete KIP-1050 we will have error classes so maybe this is less important though.
|
This needs to be cherry-picked to the 4.0 branch. |
| * This client can communicate with brokers that are version 0.10.0 or newer. Older or newer brokers may not support | ||
| * certain client features. For instance, the transactional APIs need broker versions 0.11.0 or later. You will receive an | ||
| * <code>UnsupportedVersionException</code> when invoking an API that is not available in the running broker version. | ||
| * This client can communicate with brokers that are version 2.1 or newer. Older brokers may not support |
There was a problem hiding this comment.
For producers, transaction.version needs to be set on the newer server to enable txn V2 support.
For consumers, group.version needs to be set to enable the new consumer rebalance protocol.
There was a problem hiding this comment.
That makes sense. But I think the message as written before made it sound like a newer broker version may result in some consumer/producer features not working. That seems unlikely to me. The more likely thing is that a newer broker would mean a certain consumer version is no longer supported.
Also fix a few other client javadoc issues.