You wrap a Logback file appender in AsyncAppender to cut latency. Explain the queue model, what queueSize, discardingThreshold, neverBlock and includeCallerData actually do, and which log lines you can silently lose.

## What it actually decouples Synchronous appenders write on the caller's thread and typically flush per event, so the application pays a syscall and, under contention, an appender lock. `AsyncAppender` moves the write off that thread. What it does **not** do is make logging free: enqueueing still costs, the queue is shared, and every guarantee you had about a line being on disk when the method returned is gone. Note also that `AsyncAppender` writes nothing itself. It must reference exactly one wrapped appender via a single `<appender-ref>`, and that appender does the real I/O. Pointing it at several appenders is a configuration mistake people make and then wonder why only one destination receives events. ## The queue A single bounded blocking queue of `queueSize` events, drained by one worker thread. Defaults are conservative: 256 entries. Two implications: - 256 is small for a bursty service. A burst larger than the queue hits the back-pressure or drop path within milliseconds. - One worker means ordering is preserved but throughput is bounded by the single downstream appender. Sizing is a memory decision: each queued logging event retains the message, argument references and the copied MDC map, so a very large queue on a high-cardinality MDC can hold real heap — and, worse, keeps references to argument objects alive, delaying their collection. ## discardingThreshold: the silent, level-biased drop When the queue's remaining capacity falls below `discardingThreshold`, `AsyncAppender` discards incoming events at level INFO, DEBUG and TRACE, keeping WARN and ERROR. The default threshold is `queueSize / 5`, i.e. dropping starts at 80% full — with the default 256 that is a threshold of 51, so once fewer than 51 slots remain, INFO and below stop being enqueued. The design intent is good — preserve the important lines under pressure — but the operational consequence is precisely what surprises teams: during the incident, when volume spikes, the contextual INFO lines that explain *why* the errors happened are the ones deleted, and nothing in the output says so. If you need a complete trail, set `discardingThreshold=0` and accept that you now face the full-queue decision instead. ## neverBlock: back-pressure versus loss With the queue full and no discarding available: - `neverBlock=false` (default) → the enqueue blocks the application thread until space appears. Your logging subsystem is now on the critical path, and a stalled destination (an NFS mount, a full disk, a TCP appender to a down collector) becomes an application-wide latency or thread-pool exhaustion event. - `neverBlock=true` → the non-blocking offer fails, the event is dropped, the caller continues. Availability is protected; observability is not. There is no third option inside `AsyncAppender`. Choosing is a policy call, and the honest framing is: *is a missing log line or an added tail-latency spike the worse outcome for this service?* For request-path services the usual answer is `neverBlock=true` plus alerting on drops; for audit or compliance streams the answer is blocking, or better, not using an async appender at all and writing durably instead. ## includeCallerData Caller information (class, method, file, line) is derived by walking the current thread's stack. Once the event is on the queue, the worker's stack has no relation to the origin, so the data must be captured **eagerly, on the calling thread**, at the moment of enqueue. That is exactly the expensive thing you moved to async to avoid, which is why the default is `false` — and why patterns containing `%line` or `%method` render `?` behind an `AsyncAppender` until someone sets `includeCallerData=true`. ## Shutdown Events sitting in the queue when the JVM exits are lost unless the logger context is stopped, which stops the appender and waits up to `maxFlushTime` (default 1000 ms) for the worker to drain. In containers, a hard kill after a short grace period, or an app that never stops the context, loses the tail — typically the shutdown or crash lines you most wanted. ## When to reach for it Async helps when the wrapped appender is genuinely slow or blocking (network appenders, remote syslog, heavily formatted output) or when tail latency is the target. For a plain local file appender, turning off per-event flushing often recovers most of the throughput with a far simpler failure model. Measure before adopting a component whose failure mode is *silence*. Worth knowing for contrast: Log4j2 takes a different design for the same goal, with an asynchronous logger built on a ring buffer (LMAX Disruptor) and configurable wait strategies, rather than Logback's single bounded queue plus level-biased discard. The trade-off space is the same — bounded memory, back-pressure or loss — but the knobs and defaults do not transfer between the two.