Overview

Many of the Consumer APIs provide a means for users to express that an operation should adhere to a timeout, provided as a Duration object as one of the API method parameters. Not all of the APIs allow users to provide a timeout, but of those that do, the timeout is either required or optional. 

Consumer.poll() - user provide timeout

...

Is there a better way to configure session interval and heartbeat interval?

API Timeouts

Many of the Consumer APIs provide a means for users to express that an operation should adhere to a timeout, provided as a Duration object as one of the API method parameters. Not all of the APIs allow users to provide a timeout, but of those that do, the timeout is either required or optional. 

...

Interpretation of Timeout Values

A precise definition of the timeout policy and behavior is, unfortunately, undefined. The main clues as to their interworking are based on the API-level documentation as well as the source code itself. The documentation can be a little vague and the source code is not consistent throughout the different APIs. Also, Kafka does not provide any real time guarantees, so the level of precision in describing the timeouts is rough. This leaves us in the situation in which there may be more than one way to interpret how a timeout is implemented.

API Timeouts

Required

The following Consumer APIs require a timeout:

• clientInstanceId
• poll

Optional

The following Consumer APIs provide overloaded versions that allow the user to pass in an optional timeout:

...

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 practice, timeouts are largely used to time-bound network I/O. The communication between the client and brokers is going to constitute the majority 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.

Internal Retries

In the following diagram, we see that the user has invoked a Consumer API call with a timeout:

...