LLD-011 · DESIGN PRACTICE

Logging Framework

Compose filters, immutable events and sinks while stating queue and delivery guarantees honestly.

Local Java 21 reference verified: 18 checks. Learner drafts are not executed. Author self-review; independent review pending.

Existing introductory lesson · Version 1

Understand the problem

Design a logger with severity filtering, structured fields, formatter/sink separation, failure isolation and a bounded queued sink. Explain why a successful logging call, queue admission and durable output are different events.

Before you start

• Dependency injection and narrow interfaces
• Immutable event snapshots
• Producer/consumer backpressure
• Lock scope and shutdown semantics

Scope and explicit decisions

• The core Logger invokes configured sinks synchronously outside its short sequence-allocation monitor. No global mutable logger registry, filesystem rotation, background thread, remote collector or durable storage is implemented.
• Level order is DEBUG<INFO<WARN<ERROR. Events below the configured threshold return before event construction and do not invoke sinks. Caller-side argument computation has already happened; this is not a lazy Supplier API.
• Each enabled event has a sequence allocated under the logger monitor and immutable message/field snapshot. Fields are String→String values, so Map.copyOf gives adequate defensive ownership.
• Different concurrent log calls may invoke sinks in a different order from their allocated sequence numbers. The core does not promise cross-thread ordered output. Sinks must support the concurrency their callers permit.
• One sink exception is counted and does not prevent later sinks from being called. JVM Errors are not caught. Logger restores thread interruption on InterruptedException while continuing its declared fan-out; BoundedSink restores interruption and stops that drain, leaving remaining queued records. Failed records are not retried.
• Report counts completed sink calls and failed sink calls. It does not count delivered records or even queue admissions: a drop-new BoundedSink returns normally while incrementing its own dropped counter.
• BoundedSink is an explicitly pumped queue, not an automatic asynchronous worker. write enqueues up to capacity, then drops the newest event. drain(maxEvents) has one drainer and invokes the delegate outside the queue monitor.
• Queue capacity bounds event slots, not payload bytes. One additional event may be in flight. close stops future writes but retains already queued events for explicit drain. There is no deadline, fsync guarantee or automatic flush; a blocking delegate can block the drainer.

Worked examples

Try before revealing

Requirements and invariants

R1 — Disabled levels invoke no sinks and allocate no Event. log protects I1.

R2 — Queued events cannot observe later caller-field mutations. log protects I2.

R3 — Queue length never exceeds capacity and one drainer owns delivery. drain protects I3.

R4 — Destination I/O cannot hold the queue monitor. drain protects I3.

I1: A filtered event has zero completed/failed sink calls.

I2: An Event owns an immutable String-field snapshot taken before sink invocation.

I3: Queue depth <= capacity, at most one event is in-flight under one drainer, and slow delegate I/O runs outside queue ownership.

Derive the design

Synchronous sinks first, then make buffering a composable boundary

A logger that directly writes to one output is simple, but callers are coupled to destination latency and cannot change formatting without changing output code. The reference introduces tiny Sink and Formatter ports and a TextSink composition. BoundedSink decorates a sink with explicit admission and later drain behavior. It is intentionally a manually pumped model so tests can control scheduling without sleeps.

Alternative: A background worker can call drain, but then the design needs thread ownership, interruption, shutdown/join, deadlines and retry rules. Adding a queue alone does not implement those lifecycle semantics. A well-maintained logging library is often the practical production choice; this chapter studies the component contracts.

Responsibilities and ownership

Method contracts

What, when, why and how

Each concept is attached to the requirement it protects, its implementation, an alternative and a test.

Read and run the Java reference

1import java.util.*;
2/** Small synchronous logger with an explicitly pumped bounded async sink. No background worker. */
3public final class Solution {
4    private Solution() {}
5    public enum Level { DEBUG, INFO, WARN, ERROR }
6    public record Event(long sequence,Level level,String message,Map<String,String> fields){
7        public Event{Objects.requireNonNull(level);Objects.requireNonNull(message);fields=Map.copyOf(fields);}
8    }
9    @FunctionalInterface public interface Sink { void write(Event event) throws Exception; }
10    @FunctionalInterface public interface Formatter { String format(Event event); }
11    public record Report(boolean filtered,int completedCalls,int failedCalls){}
12    public static final class TextSink implements Sink {
13        private final Formatter formatter;
14        private final java.util.function.Consumer<String> output;
15        public TextSink(Formatter formatter,java.util.function.Consumer<String> output){this.formatter=Objects.requireNonNull(formatter);this.output=Objects.requireNonNull(output);}
16        public void write(Event event){output.accept(formatter.format(event));}
17    }
18    public static final class Logger {
19        private final Level threshold;
20        private final List<Sink> sinks;
21        private long sequence;
22        public Logger(Level threshold,List<Sink> sinks){this.threshold=Objects.requireNonNull(threshold);this.sinks=List.copyOf(sinks);}
23        public Report log(Level level,String message,Map<String,String> fields){
24            Objects.requireNonNull(level);if(level.ordinal()<threshold.ordinal())return new Report(true,0,0);
25            final Event event;synchronized(this){event=new Event(Math.incrementExact(sequence),level,message,fields);sequence=event.sequence();}
26            int delivered=0,failed=0;
27            for(var sink:sinks)try{sink.write(event);delivered++;}catch(Exception ex){failed++;if(ex instanceof InterruptedException)Thread.currentThread().interrupt();}
28            return new Report(false,delivered,failed);
29        }
30    }
31    public static final class BoundedSink implements Sink {
32        private final int capacity;
33        private final Sink delegate;
34        private final ArrayDeque<Event> queue=new ArrayDeque<>();
35        private boolean closed,draining;
36        private long dropped,failed,delivered;
37        public BoundedSink(int capacity,Sink delegate){if(capacity<1)throw new IllegalArgumentException("capacity");this.capacity=capacity;this.delegate=Objects.requireNonNull(delegate);}
38        public synchronized void write(Event event){Objects.requireNonNull(event);if(closed)throw new IllegalStateException("closed");if(queue.size()==capacity){dropped++;return;}queue.addLast(event);}
39        // Single drainer. I/O runs outside the queue monitor; reentrant drain is rejected.
40        public void drain(int maxEvents){
41            if(maxEvents<1)throw new IllegalArgumentException("maxEvents");
42            synchronized(this){if(draining)throw new IllegalStateException("already draining");draining=true;}
43            try{
44                for(int processed=0;processed<maxEvents;processed++){final Event event;synchronized(this){event=queue.pollFirst();}if(event==null)return;
45                    try{delegate.write(event);synchronized(this){delivered++;}}catch(Exception ex){synchronized(this){failed++;}if(ex instanceof InterruptedException){Thread.currentThread().interrupt();return;}}
46                }
47            }finally{synchronized(this){draining=false;notifyAll();}}
48        }
49        /** Stops admission. Already accepted events remain queued and may be drained afterwards. */
50        public synchronized void close(){closed=true;}
51        public synchronized int queued(){return queue.size();}
52        public synchronized long dropped(){return dropped;}
53        public synchronized long failed(){return failed;}
54        public synchronized long delivered(){return delivered;}
55    }
56}
57

Complexity and limits

• Logger fan-out costs O(F+S) for F copied fields and S sink calls, excluding arbitrary sink work. Sequence allocation is serialized, but sink calls are not globally ordered.
• BoundedSink queue admission is O(1); drain(N) performs at most N delegate calls and O(N) queue operations. Destination cost and blocking dominate latency.
• Queue storage is O(C×event size) plus one in-flight event and metric fields. Because message/field bytes are unbounded, fixed C is not a strict byte-memory limit.
• TextSink formatting cost depends on Formatter and output contract. There is no fsync, file rotation, durable replay or automatic retry implementation.

Walk through the actual reference

These walkthrough fixtures are emitted only after the Java harness verifies their operations and expected state. Concurrency tests additionally exercise competing callers.

Mistakes and counterexamples

Engineer → Senior → Staff

Return to the lesson →

Provenance and scope of evidence

Original teaching material. The local contract is implemented by Solution.java and tested by Test.java on Java 21. Distributed persistence, real provider/device adapters and deployment are not claimed.

Reference verification is not independent editorial review, production deployment verification or a claim that distributed adapters are implemented.