THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
| Table of Contents |
|---|
Status
Current state: Under Discussion
...
Please keep the discussion on the mailing list rather than commenting on the wiki (wiki discussions get unwieldy fast).
Motivation
This KIP could be seen as an spin-off of KIP-740: Clean up public API in TaskId and fix TaskMetadata#taskId(). During the one of the Pull Requests that were created to implement the aforementioned KIP, it became apparent that TaskMetadata was never a class that the user would ever need to instantiate, but rather an API for exposing metadata. For this reason, it would make sense to separate the public interface from the internal implementation, hence this proposal to create the TaskMetadata interface. See https://github.com/apache/kafka/pull/10755#discussion_r639338584 for further context on this topic.
Also it is important to notice that the goal of this KIP needs to still be consistent with that of KIP-740, which was to not expose TaskID as a String in the public APIs.
For reasons described in further detail under "Public Interfaces" this KIP should be part of release 3.0.0, so we can keep the APIs consistent without the need to wait for a full deprecation cycle.
Public Interfaces
Create a new Interface named TaskMetadata under package org.apache.kafka.streams, which will contain all currently non deprecated methods:
Within this KIP discussion, it was also pointed out that ThreadMetadata shares the same problems as TaskMetadata. Hence, this KIP proposes, as well, to convert ThreadMetadata into an interface and keep the implementation as an internal class. The reasoning behind this is the same as with the previous class, ThreadMetadata was never meant to be instantiated by end users, but was rather meant as an API.
Also it is important to notice that the goal of this KIP needs to still be consistent with that of KIP-740, which was to not expose TaskID as a String in the public APIs.
For reasons described in further detail under "Public Interfaces" this KIP should be part of release 3.0.0, so we can keep the APIs consistent without the need to wait for a full deprecation cycle.
Public Interfaces
Create a new Interface named TaskMetadata under package org.apache.kafka.streams, which will contain all currently non deprecated methods:
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
/**
* Represents the state of a single task running within a {@link KafkaStreams} application.
*/
public interface TaskMetadata {
/**
| ||||||||
| Code Block | ||||||||
| ||||||||
/** * Represents the state of a single task running within a {@link KafkaStreams} application. */ public interface TaskMetadata { /** * @return the basic task metadata such as subtopology and partition id */ TaskId taskId(); /** * This function will return a set of the current TopicPartitions */ Set<TopicPartition> topicPartitions(); /** * This function will return a map of TopicPartitions and the highest committed offset seen so far */ Map<TopicPartition, Long> committedOffsets(); /** * This function will return a map of TopicPartitions and the highest offset seen so far in the Topic */ Map<TopicPartition, Long> endOffsets(); /** * This function will return the time task idling started, if the task is not currently idling it will return empty */ Optional<Long> timeCurrentIdlingStarted(); } |
Additionally, TaskMetadata under org.apache.kafka.streams.processor, will be deprecated:
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
/**
* Represents the state of a single task running within a {@link KafkaStreams} application.
* @deprecated since 3.0, use {@link org.apache.kafka.streams.TaskMetadata} instead
*/
@Deprecated
public class TaskMetadata {
...
} |
Furthermore, the method getTaskId newly introduced in KIP-740 (but not yet released) will be removed, as it won't be needed any more. For this reason, it makes sense to include this KIP in release 3.0.0 so we can avoid a full cycle of deprecation for this newly introduced method.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
// This method will be removed in this KIP
/**
* @return the basic task metadata such as subtopology and partition id
*/
public TaskId getTaskId() {
return taskId;
} |
/**
* Compares the specified object with this TaskMetadata. Returns {@code true} if and only if the specified object is
* also a TaskMetadata and both {@code taskId()} and {@code topicPartitions()} are equal.
*/
boolean equals(final Object o);
/**
* Returns the hash code value for this TaskMetadata. The hash code of a list is defined to be the result of the following calculation:
* <pre>
* {@code
* Objects.hash(taskId(), topicPartitions());
* }
* </pre>
*/
int hashCode();
} |
Additionally, TaskMetadata under org.apache.kafka.streams.processor, will be deprecatedThere is one additional change that needs to be performed in ThreadMetadata. Currently, this class uses the newly deprecated TaskMetada class in its constructor and it's returned in activeTasks() and standbyTasks() methods. We should deprecate those and add new methods and constructor referencing the new Interface:
| Code Block | |||||||||
|---|---|---|---|---|---|---|---|---|---|
| |||||||||
/**
* Represents the state of a single task running within a {@link KafkaStreams} application.
* @deprecated since 3.0, use {@link org.apache.kafka.streams.TaskMetadata} instead
*/
@Deprecated
public class TaskMetadata {
...
} |
Furthermore, the method getTaskId newly introduced in KIP-740 (but not yet released) will be removed, as it won't be needed any more. For this reason, it makes sense to include this KIP in release 3.0.0 so we can avoid a full cycle of deprecation for this newly introduced method.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
// This method will be removed in this KIP
/**
* @return the basic task metadata such as subtopology and partition id
*/
public TaskId getTaskId() {
return taskId;
} |
ThreadMetadata class under org.apache.kafka.streams.processor will be deprecated:
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
/**
* Represents the state of a single thread running within a {@link KafkaStreams} application.
* @deprecated since 3.0 use {@link org.apache.kafka.streams.ThreadMetadata} instead
*/
@Deprecated
public class ThreadMetadata {
...
} |
A new interface named ThreadMetadata will be introduced under org.apache.kafka.streams:
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
/** * Represents the state of a single thread running within a {@link KafkaStreams} application. */ public interface ThreadMetadata { /** * @return the state of the Thread */ String threadState(); /** * @return the name of the Thread */ String threadName(); /** * This function will return the set of the {@link TaskMetadata} for the current active tasks */ Set<TaskMetadata> activeTasks(); /** * This function will return the set of the {@link TaskMetadata} for the current standby tasks */ Set<TaskMetadata> standbyTasks(); /** * @return the consumer Client Id */ String consumerClientId(); /** * @return the restore consumer Client Id */ String restoreConsumerClientId(); /** * This function will return the set of Client Ids for the producers */ Set<String> producerClientIds(); /** * @return the admin Client Idimport org.apache.kafka.streams.TaskMetadata; public class ThreadMetadata { .... /** * @deprecated since 3.0 use {@link #ThreadMetadata(String, String, String, String, Set, Set, Set, String)} instead */ @Deprecated public ThreadMetadata(final String threadName,String adminClientId(); /** * Compares the specified object with this ThreadMetadata. Returns {@code true} if and only if the specified final String threadState,object is * also a TaskMetadata and both {@code threadName()} are equal, {@code threadState()} are equal, {@code activeTasks()} finalcontain Stringthe mainConsumerClientId,same * elements, {@code standbyTasks()} contain the same elements, {@code mainConsumerClientId()} are equal, {@code restoreConsumerClientId()} final* Stringare restoreConsumerClientIdequal, {@code producerClientIds()} are equal, {@code producerClientIds} contain the same elements, and {@code adminClientId()} are equal. */ boolean final Set<String> producerClientIds,equals(Object o); /** * Returns the hash code value for this TaskMetadata. The hash code of a list is defined finalto Stringbe adminClientId, the result of the following calculation: * <pre> * {@code final Set<org.apache.kafka.streams.processor.TaskMetadata> activeTasks, * Objects.hash( * threadName, * final Set<org.apache.kafka.streams.processor.TaskMetadata> standbyTasks) { threadState, * this.mainConsumerClientId = mainConsumerClientId; this.restoreConsumerClientId = restoreConsumerClientId;activeTasks, * this.producerClientIds = producerClientIds; standbyTasks, this.adminClientId = adminClientId; * this.threadName = threadName; mainConsumerClientId, this.threadState = threadState; * this.activeTasks = Collections.unmodifiableSet(activeTasks.stream().map(metadata -> new TaskMetadataImpl(TaskId.parse(metadata.taskId()) restoreConsumerClientId, * metadata.topicPartitions()producerClientIds, * metadata.committedOffsets(), adminClientId); * </pre> */ int hashCode(); } |
Additionally, KafkaStreams class needs to adapted to return the new ThreadMetadata interface, and have the old method (returning the old class) deprecated as follows:
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
/** metadata.endOffsets(), metadata.timeCurrentIdlingStarted())).collect(Collectors.toSet())); * Returns runtime this.standbyTasksinformation = Collections.unmodifiableSet(standbyTasks.stream().map(metadata -> new TaskMetadataImpl(TaskId.parse(metadata.taskId()), about the local threads of this {@link KafkaStreams} instance. * metadata.topicPartitions(), * @return the set of {@link org.apache.kafka.streams.processor.ThreadMetadata}. * @deprecated since 3.0 use {@link metadata.committedOffsets#threadsMetadata(),} */ metadata.endOffsets(),@Deprecated public Set<org.apache.kafka.streams.processor.ThreadMetadata> localThreadsMetadata() { return metadatathreadsMetadata().timeCurrentIdlingStartedstream())).collect(Collectors.toSet()));map(threadMetadata -> new org.apache.kafka.streams.processor.ThreadMetadata( } public ThreadMetadata(final String threadMetadata.threadName(), threadMetadata.threadState(), final String threadState, threadMetadata.consumerClientId(), threadMetadata.restoreConsumerClientId(), final String mainConsumerClientId, threadMetadata.producerClientIds(), threadMetadata.adminClientId(), final String restoreConsumerClientId, threadMetadata.activeTasks().stream().map(taskMetadata -> new TaskMetadata( final Set<String> producerClientIds, taskMetadata.taskId().toString(), final Set<TaskMetadata> activeTasks, taskMetadata.topicPartitions(), final Set<TaskMetadata> standbyTasks, taskMetadata.committedOffsets(), final String adminClientId) {taskMetadata.endOffsets(), this.mainConsumerClientId = mainConsumerClientId; this.restoreConsumerClientId = restoreConsumerClientId; taskMetadata.timeCurrentIdlingStarted()) this.producerClientIds = producerClientIds; this.adminClientId = adminClientId; ).collect(Collectors.toSet()), this.threadName = threadName; this.threadState = threadState; threadMetadata.standbyTasks().stream().map(taskMetadata -> new TaskMetadata( this.activeTasks = Collections.unmodifiableSet(activeTasks); this.standbyTasks = Collections.unmodifiableSet(standbyTasks);taskMetadata.taskId().toString(), } public Set<TaskMetadata> getActiveTasks() { return activeTasks; } taskMetadata.topicPartitions(), public Set<TaskMetadata> getStandbyTasks() { return standbyTasks; } /**taskMetadata.committedOffsets(), * @deprecated since 3.0 use {@link #getActiveTasks()} */ @Deprecated public Set<org.apache.kafka.streams.processor.TaskMetadata> activeTaskstaskMetadata.endOffsets(), { return activeTasks.stream().map(metadata -> new org.apache.kafka.streams.processor.TaskMetadata(metadata.taskId().toString(), taskMetadata.timeCurrentIdlingStarted()) metadata.topicPartitions).collect(Collectors.toSet(),))) metadata.committedOffsets(),.collect(Collectors.toSet()); } /** * Returns runtime metadata.endOffsets(), metadata.timeCurrentIdlingStarted())).collect(Collectors.toSet()); } information about the local threads of this {@link KafkaStreams} instance. /** * @deprecated@return sincethe 3.0set useof {@link #getStandbyTasks()ThreadMetadata}. */ @Deprecated public Set<ThreadMetadata> threadsMetadata() { public Set<org.apache.kafka.streams.processor.TaskMetadata> standbyTasks() { final Set<ThreadMetadata> threadMetadata = returnnew standbyTasks.streamHashSet<>().map(metadata -> ; processStreamThread(thread -> { new org.apache.kafka.streams.processor.TaskMetadata(metadata.taskId().toString(), synchronized (thread.getStateLock()) { if metadata(thread.topicPartitionsstate(), != StreamThread.State.DEAD) { metadata.committedOffsets(), threadMetadata.add(thread.getThreadMetadata()); } metadata.endOffsets(), metadata.timeCurrentIdlingStarted())).collect(Collectors.toSet()); } .... } |
This last change could be avoided, if we allow ourselves to break source compatibility for this particular section. Otherwise, we need to go for a cycle of deprecation for activeTasks() and standbyTasks() for then, to move the non-normative getActiveTasks() and getStandbyTasks() back to the proper naming scheme.
Proposed Changes
}
});
return threadMetadata;
} |
Proposed Changes
By introducing a new TaskMetadata interface on a different package, we are able to keep the same name (no need to come up with some forced name), and also, we are freed from carrying over changes like the one introduced in https://github.com/apache/kafka/pull/10755 where a method getTaskId was introduced (going against Kafka naming convention) because taskId was already taken and needed to be deprecated.
Together with this change, a new class TaskMetadataImpl will be created under org.apache.kafka.streams.processor.internals, which will implement the aforementioned interface with the implementation present on the org.apache.kafka.streams.processor.TaskMetadata. The rest of the Kafka code base using the newly deprecated TaskMetadata will be migrated to use the new classes instead.
The changes related to ThreadMetadata follow a similar pattern. A new class ThreadMetadataImpl By introducing a new interface on a different package, we are able to keep the same name (no need to come up with some forced name), and also, we are freed from carrying over changes like the one introduced in https://github.com/apache/kafka/pull/10755 where a method getTaskId was introduced (going against Kafka naming convention) because taskId was already taken and needed to be deprecated.
Together with this change, a new class TaskMetadataImpl will be created under org.apache.kafka.streams.processor.internals, which will implement the aforementioned interface with the implementation present on the newly created interface org.apache.kafka.streams.processor.TaskMetadataThreadMetadata. The rest of the Kafka code base using the newly deprecated TaskMetadata will be migrated to use the new newly created classes instead.
Also, by introducing a new interface interfaces altogether, we ease the migration of any possible current user of this class meant to be for internal use onlythe newly deprecated classes, offering a smooth transition to the new APIs.
Compatibility, Deprecation, and Migration Plan
As we create are creating a new interface, these changes are 100% compatible. Users who currently use org.apache.kafka.streams.processor.TaskMetadata, should migrate to org.apache.kafka.streams.TaskMetadata..
Same goes for users who currently use org.apache.kafka.streams.processor.ThreadMetadata, they should migrate to org.apache.kafka.streams.ThreadMetadata.
Users using KafkaStreams#localThreadsMetadata should migrate to KafkaStreams#threadsMetadata.
Classes Class org.apache.kafka.streams.processor.TaskMetadata and org.apache.kafka.streams.processor.ThreadMetadata will be deprecated and removed in future releases.
Rejected Alternatives
An alternative that was rejected, was to directly transform org.apache.kafka.streams.TaskMetadata into an interface with this change. This was seen as a breaking change as the current constructor won't be present any more in this alternative, making possible users of this fail to compile.
...