Introduction

AsyncAppender in Logback moves log event delivery off the application thread by buffering events in a queue. The queueSize parameter controls how much pending log traffic the appender can absorb before producers start blocking or lower-priority events are discarded.

What queueSize Actually Controls

When you wrap a file or console appender in AsyncAppender, Logback creates an internal queue. Application threads push logging events into that queue, and a worker thread forwards those events to the real destination. A larger queue can smooth out spikes, but it also increases memory use and can hide slow downstream logging for longer.

A minimal Logback configuration looks like this:

1<configuration>
2  <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
3    <file>logs/app.log</file>
4    <encoder>
5      <pattern>%d %-5level %logger - %msg%n</pattern>
6    </encoder>
7  </appender>
8
9  <appender name="ASYNC" class="ch.qos.logback.classic.AsyncAppender">
10    <queueSize>8192</queueSize>
11    <discardingThreshold>0</discardingThreshold>
12    <neverBlock>true</neverBlock>
13    <appender-ref ref="FILE" />
14  </appender>
15
16  <root level="INFO">
17    <appender-ref ref="ASYNC" />
18  </root>
19</configuration>

Here, the queue can hold up to 8192 events waiting to be written. That is not automatically better than a smaller number. It only makes sense if the application produces bursty logs and the target appender can catch up.

Choosing a Queue Size

A practical choice depends on three things:

1. Peak logging rate.
2. Average time to flush an event to the destination.
3. How much memory you are willing to spend on logging.

If your app writes a few hundred events per second to a local file, a moderate queue is usually enough. If it writes heavy structured logs during traffic bursts, you may need more headroom. The point is not to maximize the value. The point is to cover short spikes without letting logging become an invisible memory sink.

A good starting approach is:

• keep the queue modest in development
• test under realistic load
• watch whether events are dropped or producer threads block
• increase only when measurements justify it

Programmatic Configuration Example

If you configure Logback in code, you can set the queue size directly on the appender instance.

1import ch.qos.logback.classic.AsyncAppender;
2import ch.qos.logback.classic.LoggerContext;
3import ch.qos.logback.classic.encoder.PatternLayoutEncoder;
4import ch.qos.logback.core.ConsoleAppender;
5
6LoggerContext context = new LoggerContext();
7
8PatternLayoutEncoder encoder = new PatternLayoutEncoder();
9encoder.setContext(context);
10encoder.setPattern("%d %-5level %logger - %msg%n");
11encoder.start();
12
13ConsoleAppender consoleAppender = new ConsoleAppender();
14consoleAppender.setContext(context);
15consoleAppender.setEncoder(encoder);
16consoleAppender.start();
17
18AsyncAppender asyncAppender = new AsyncAppender();
19asyncAppender.setContext(context);
20asyncAppender.setName("ASYNC");
21asyncAppender.setQueueSize(4096);
22asyncAppender.setDiscardingThreshold(0);
23asyncAppender.setNeverBlock(false);
24asyncAppender.addAppender(consoleAppender);
25asyncAppender.start();

The key call is setQueueSize(4096). Call it before start() so the appender initializes with the intended capacity.

Interactions With Other Async Settings

queueSize is only one part of the behavior.

discardingThreshold controls when lower-priority events can be dropped as the queue fills. If you care about keeping debug logs during bursts, you may want this at 0. If you only care about warnings and errors, letting debug events drop can protect throughput.

neverBlock controls what producer threads do when the queue is full. If it is false, a logging call may block until there is room. If it is true, the app favors application throughput and may lose events instead.

The right combination depends on whether logs are audit-critical or operationally useful but disposable.

Common Pitfalls

One mistake is treating queue size as a pure performance knob. A larger queue does not make the destination faster. If your file system, network share, or encoder is slow, the queue only delays the moment you notice the bottleneck.

Another mistake is setting a very large queue and then ignoring memory impact. Each queued logging event holds message data and metadata. Under sustained overload, the queue can become a surprisingly expensive buffer.

A third problem is forgetting how neverBlock changes failure behavior. Teams sometimes increase queueSize, set neverBlock to true, and assume logging is now safe. In reality, they may still lose events during peak load, just later and less visibly.

Finally, do not tune this setting in isolation. If log volume is the real issue, reducing noisy log statements, sampling repetitive messages, or writing structured logs more efficiently often gives better results than queue inflation.

Summary

• 'queueSize defines how many log events AsyncAppender can buffer.'
• Pick the value from measured traffic and destination speed, not guesswork.
• Set it before calling start() when configuring programmatically.
• Tune it together with discardingThreshold and neverBlock.
• A larger queue absorbs spikes, but it does not fix a slow logging backend.