Page History

...

In this document, we refer to the timeout that the user supplies to an API as the API timeout. This is a timeout that covers the entirety time spent on the Consumer API call. The user should be free to treat the API timeout like a black box; it is the upper-bound on the length of time spent executing that API call. When a timeout-based Consumer API is invoked, that timeout value provides an upper-bound for the aggregation of the entire set of operations required by that API call. That is, the length of time for all the constituent operations of that API call must be less than or equal to the timeout provided by the user.

In the overview, we stated that the Consumer APIs provides overloaded versions of many methods with an optional timeout. Say the user calls commitSync() (i.e. the version of the commit method that does not include a timeout)—is it then assumed that the method will run forever? The documentation for default.api.timeout.ms states this about the configuration option:

Specifies the timeout (in milliseconds) for client APIs. This configuration is used as the default timeout for all client operations that do not specify a timeout parameter.

So the implementation of method such as commitSync() essentially just calls its sibling version (commitSync(Duration timeout)) like this:

public void commitSync() {
    Duration timeout = Duration.ofMillis(defaultApiTimeoutMs); 
    commitSync(timeout);
}

Network I/O Timeouts

In practice, timeouts are largely used to time-bound I/O. In the case of a Kafka client, there is no disk I/O, so we can focus our attention solely on network I/O. The communication between the client and brokers over the network is going to constitute the bulk of the time for many operations. Allowing the user to provide an upper bound on the total time of these operations provides some protection against network issues.

...