Notes
Requirements
The requirements. Four levels: debug, info, warn and error. Loggers have names like checkout or payments, and the configuration sets a level per name. Output goes to several sinks, console, file and a remote collector, each with its own minimum level and format, plain text or JSON. Many threads log at once, logging must not block the application, and a clean shutdown must not lose lines. File rotation is out of scope.
Ask the questions that change the design. Synchronous or asynchronous writes? Asynchronous, so callers only enqueue. What happens when the buffer is full? Configurable: block the caller, or drop and count. Must lines be ordered across threads? Order within each thread is enough. If the remote collector is down, buffer and retry, but never throw into business code.
- levels: DEBUG, INFO, WARN, ERROR
- named loggers: checkout, payments
- level per logger name, by config
- sinks: console, file, remote
- each sink: own level and format
- formats: plain text, JSON
- many threads log at once
- logging must not block the app
- no lost lines on clean shutdown
- out of scope: log rotation
- sync or async writes?
- async: callers only enqueue
- queue full?
- configurable: block or drop
- order across threads?
- per thread order is enough
- remote sink down?
- buffer, retry, never throw
- level change at runtime?
- nice to have, via config
Entities
The entities. A log manager hands out named loggers. A logger checks the level and turns a call into a log event. The event goes to a dispatcher, which runs it through a chain of handlers. Each handler has a minimum level, a formatter that turns the event into text, and a sink that writes the text somewhere. Separating formatting from writing is the key move: any format can go to any destination.
Class diagram
In code: the level is an enum ordered by severity, with an at-least check. A log event is an immutable record of the time, level, logger name, thread and message, so it can safely cross threads. A formatter turns an event into a string, and a sink writes a string and can flush and close. Three tiny interfaces are the whole extension surface of the library.
enum Level { DEBUG, INFO, WARN, ERROR;
boolean atLeast(Level min) }
record LogEvent(Instant time, Level level,
String logger, String thread,
String message)
interface Formatter {
String format(LogEvent e); }
interface Sink extends AutoCloseable {
void write(String line);
default void flush() {} } Cheap filtering
Most log calls are filtered out, so filtering must be nearly free. The logger compares the level before doing anything else. Messages can be passed as a supplier, a small lambda, so an expensive message like a cart dump is only built if the line will actually be written. The demo proves it: a filtered debug call never runs its supplier. The clock is injected too, which keeps tests deterministic.
void log(Level l, Supplier<String> msg) {
if (!l.atLeast(level)) return;
out.submit(new LogEvent(clock.get(), l,
name, thread, msg.get()));
}
debug(() -> "cart " + dumpCart())
logger at INFO: dumpCart() never runs
demo asserts the supplier ran
once, not twice Configuration
Configuration is a root level plus overrides by logger name, and the most specific match wins. With the root at info and payments at debug, checkout logs at info, while payments dot card inherits debug from its parent. Match whole name segments, key plus a dot, so a logger called payments x does not accidentally inherit. In a real library this config comes from a file and can be reloaded at runtime.
root = INFO overrides: payments = DEBUG checkout -> INFO (root) payments -> DEBUG payments.card -> DEBUG (prefix) paymentsx -> INFO (not a child) match: name equals key, or starts with key + "."
Factory
Loggers come from a factory. The log manager caches one logger per name with compute-if-absent, so asking twice returns the same instance, and the level is resolved once instead of on every call. Real libraries make the manager a process-wide singleton for convenience. In the design, say that you pass it explicitly so each test can build its own with a fake clock and memory sinks.
loggers.computeIfAbsent(name, n ->
new Logger(n, config.levelFor(n),
dispatcher, clock))
same name: same Logger instance
level resolved once, not per call
usually a singleton per process;
passed explicitly here so tests
can build their own Strategy: formats
Formatting is a strategy. Plain text puts the time, level, logger name and message on one line for humans. JSON emits one object per line for machines, so a log platform can search by field, and it must escape quotes inside the message. A pattern-string formatter or logfmt is another implementation. Because the handler holds the formatter, the same event can be plain on the console and JSON to the collector.
PLAIN: time level [name] message
2026-03-02T09:00:00Z INFO
[checkout] order placed
JSON: {"ts":..., "level":"ERROR",
"logger":"payments.card",
"msg":"retry failed"}
escape quotes in JSON
logfmt, pattern strings: new ones Sinks
Sinks are where the text goes. The console sink prints. The file sink wraps a buffered writer and flushes once per batch rather than once per line, which is a big speed difference. The remote sink collects lines and sends them in batches, one network call per batch instead of one per line, and flush sends whatever is left. A database sink or a message queue sink is just one more class.
ConsoleSink: System.out.println FileSink: BufferedWriter, flush per batch, close at the end RemoteSink(batchSize): pending.add(line) if size >= batchSize: send batch flush(): send what is left one network call per batch, not one per line
Chain of Responsibility
Handlers form a Chain of Responsibility. Each handler checks whether the event meets its own minimum level, writes it if so, and always passes the event to the next handler. So the console shows warnings and above, the file keeps everything, and only errors go to the remote collector as JSON. Adding a destination is adding a link, and no handler knows how many others exist.
if (e.level().atLeast(min)) sink.write(formatter.format(e)); if (next != null) next.handle(e); console(WARN, PLAIN) .then(file(DEBUG, PLAIN)) .then(remote(ERROR, JSON)) add a sink: add a link skip a sink: it just passes on
Flow: one log call
Follow one call. Checkout calls info with order placed. The logger checks the level, builds an immutable event and drops it on the dispatcher's queue, and the caller returns immediately. Later, the single writer thread takes the event and runs it through the chain: the console skips it because it is below warn, the file writes it, and the remote handler skips it. The application thread never touched a disk or a socket.
Async buffering
The dispatcher is the heart of async logging. A bounded blocking queue sits between the application threads and one writer thread. The writer blocks until there is an event, then drains up to two hundred and fifty five more in one go, runs them all through the chain and flushes once. One writer means the sinks are only ever touched by one thread, so they need no locks, and the bound means a logging storm cannot eat all the memory.
ArrayBlockingQueue<LogEvent> queue writer thread: batch.add(queue.take()) queue.drainTo(batch, 255) for (e : batch) chain.handle(e) chain.flushAll() // once per batch one writer: sinks need no locks bounded: memory cannot run away
Overflow policy
When the queue is full, there are two honest choices. Block, which applies back-pressure and never loses a line: right for audit logs. Or drop, using offer, and count what was dropped: right for noisy debug output on a latency critical path. Either way, expose the dropped count as a metric. The demo fills a queue of four with ten lines under the drop policy: four are written and six are counted as dropped.
DROP: if (!queue.offer(e))
dropped.incrementAndGet()
BLOCK: queue.put(e) // back-pressure
DROP for debug noise and
latency-critical paths
BLOCK for audit logs
report the dropped count
as a metric Concurrency
Concurrency is simple because only the queue is shared. Events are immutable, loggers sit in a concurrent map, sinks are touched only by the writer, and the drop counter is atomic. Shutdown is the subtle bit: put a stop marker on the queue behind everything already waiting, join the writer thread and then close the sinks. A boolean flag would lose whatever was still queued. The demo logs ten thousand lines from four threads and checks the file has every one.
- callers share only the queue
- events: immutable records
- loggers: ConcurrentHashMap
- sinks: touched by one thread
- dropped: AtomicLong
- shutdown: put a STOP marker
- behind all pending events,
- join the writer, close sinks
- writer is a daemon thread
Extensibility
Extensions fit the same three interfaces. File rotation is a rolling file sink that switches files by size or by day. Remote retries add backoff and spill to a local file when the collector is down. A context map carries a request id on every event. Sampling is a handler that keeps one debug line in a hundred. Reloading configuration updates logger levels in place so existing references keep working.
- rotation: a RollingFileSink
- by size or by day
- remote retry: backoff +
- a local spill file
- context: MDC map on the event
- (request id, user id)
- sampling: a handler that keeps
- 1 in 100 debug lines
- reload config: swap levels
- in place, loggers keep refs
Testing
The full code is below the player. The demo wires the console at warn, the file at debug and the remote sink at error with JSON in batches of two. It proves a filtered debug message is never built, checks the console and remote outputs, logs ten thousand lines from four threads and finds exactly ten thousand and five in the file, and fills a small queue under the drop policy to get exactly six drops.
2026-03-02T09:00:00Z WARN [checkout] stock low for item 42 2026-03-02T09:00:00Z ERROR [payments.card] gateway timeout File sink: 10005 lines, first: ... INFO [checkout] order placed Remote sink: 1 batch, 2 ERROR lines as JSON DROP policy: queue of 4, 10 logged, 4 written, 6 dropped
Follow-ups
Expect follow-ups. Why one writer? Sinks stay lock free and per thread order is preserved. What about a crash? Anything still queued is lost, so some teams write errors synchronously. A slow remote collector gets its own queue so it cannot stall the file sink. A sink that itself logs must be guarded against infinite recursion. And one queue keeps each thread's lines in order across every sink.
- why one writer thread?
- what if the app crashes?
- unflushed lines are lost:
- flush errors synchronously
- remote collector is slow?
- its own queue, never block
- logging inside a sink?
- guard against recursion
- per-thread order across sinks?
- one queue keeps it
Say it like this
The short version. Loggers check the level first and build messages lazily. Events are immutable records placed on a bounded queue, and a single writer thread drains them in batches through a chain of handlers, each a level, a formatter and a sink. When the queue is full you either block or drop and count, and shutdown uses a stop marker so nothing queued is lost.
- "Loggers check the level first
- and build messages lazily. Events
- are immutable and go on a
- bounded queue; one writer drains
- batches through a chain of
- handlers, each a level, a
- formatter and a sink. Full queue:
- block or drop and count."