onDropped property
Called with entries that will never be delivered.
Three things reach it: an entry the full queue refused (see
maxQueueSize), a batch that spends its maxRetries budget, and
entries handed back to the retry buffer after close was called,
which can never be processed. Use it to persist them somewhere
durable, or at least to count them.
Leaving it unset does not hide the loss: the publisher then says so
itself. The first one prints a line at once; the rest are counted, and
the count is printed by the next loss to arrive more than five seconds
later — widening to a minute while the losses keep coming, and back to
five once they stop — or by close, whichever comes first.
There is no timer behind any of that, deliberately: a pending timer is
a live root for the event loop, and a dropped log must not buy the
process five more seconds of life. The consequence is worth knowing.
A burst that ends without a later loss and without a close — the
shape a synchronous loop of a hundred thousand logs takes — is
announced by that first line and never counted. Pass
onDropped: (_) {} to silence all of it.
It says it with print, which means the application's stdout. For
most programs that is the console and the point; for a program whose
stdout carries a protocol — a CLI with --json, a server over stdio —
it is a line in the middle of the stream. Two ways out, and the
package deliberately takes neither by default: onDropped: (_) {},
which drops the losses in silence again, or a print of your own —
print goes through the current Zone, so an application that
redirects it redirects this too, and a redirect that throws is caught
rather than passed on to the logging call.
A throwing handler does not derail the shutdown: its own error goes to the current zone.
Implementation
final void Function(List<E> entries)? onDropped;