Status

Current state: Under Discussion

Discussion thread: here 

JIRA: Unable to render Jira issues macro, execution error.  

Please keep the discussion on the mailing list rather than commenting on the wiki (wiki discussions get unwieldy fast).

Motivation

Currently only some exceptions that occur during processing are wrapped as a StreamsException, which complicates the logic required by a user custom StreamsUncaughtExceptionHandler. It would be cleaner to ensure that all exceptions thrown to the user/handler are wrapped (exactly once) as a StreamsException. Further, many exceptions can be traced back to a particular task that's experiencing an error specific to that part of the topology, or that partition, etc. It can be helpful to have that information when determining how to handle the exception, as well as for debugging purposes. We propose to add a TaskId field to the StreamsException class to help users identify the source of an exception.

Public Interfaces

This KIP will add a new API to the StreamsException class, to expose the TaskId:

class StreamsException {
    /**
     * @return  the {@link TaskId} that this exception originated from, or {@link Optional#empty()} if the exception
     *          cannot be traced back to a particular task. Note that the {@code TaskId} being empty does not
     *          guarantee that the exception wasn't directly related to a specific task.
     */
     public Optional<TaskId> taskId() {
        return taskId;
    }
}

Proposed Changes

This KIP proposes to

1. Make sure every exception that is thrown up to the uncaught exception handler, whether that be the new StreamsUncaughtExceptionHandler or the old generic UncaughtExceptionHandler, is wrapped as a StreamsException.
2. Add a new TaskId field to the StreamsException class, with a getter API to expose it. This field will be set for any exception that originates from, or is tied to, a specific task. For example:
   1. Task timeout (ie exceeds the configured task.timeout.ms value
   2. User processing error or other exception thrown from Task#process
   3. Exceptions arising from task management, such as suspending/closing/flushing/etc 

Note: some exceptions that can theoretically be traced back to a particular task are going to be out of scope for this KIP. For example, some Consumer/Producer exceptions may refer to a topic that corresponds to a specific task. Tackling all possible task-specific exceptions may be considered for followup work, but will not be included in this KIP.

Compatibility, Deprecation, and Migration Plan

N/A – just adding a new API

Rejected Alternatives

None