The documentation of the autoFlush seems to be confusing (to me)

[wind57]

The documentation of auto-flush seems to be confusing, I can't properly grasp it (and I've ran this question to 3 of my colleagues):

Set autoFlush to {@code true} if you have configured the producer's
{@code linger.ms} to a non-default value and wish send operations on this template
to occur immediately, regardless of that setting, or if you wish to block until the
broker has acknowledged receipt according to the producer's {@code acks} property.

We indeed set the linger.ms to a non-default value and have the autoFlush=true. What we observe is that linger.ms is not respected and each message is sent immediately to the brokers. This is easily tracked by us if we look at record_queue_time_avg metric, which is far below our setting of linger.ms.

If that is indeed expected, than imho, the documentation could be improved, something along the lines of :

Set autoFlush to {@code true} if you wish for the send operations on this template
to occur immediately, regardless of what linger.ms is set to. This will also block until the
broker has acknowledged receipt according to the producer's {@code acks} property.

The difference is minor, but makes a clear statement, without any additional fuss on what autoFlush does. To me, this does not make the reader confused as it leaves no room for interpretation.

Thank you for looking into this.

[garyrussell]

On reflection; I wish we had never added the option. It would rarely (if ever) be used. Most commonly, a flush operation might be called after sending a bunch of records, to pre-empt the linger.ms. It makes no sense to flush after every send.