On this page

Design a Logging Framework

"Design a logger" sounds like the easiest prompt on the list. Everyone has called log.info(...) thousands of times. That familiarity is the trap. Candidates who treat it as easy write a Logger class with a switch on level and a System.out.println, and then have nothing to say when the interviewer asks what happens when the disk is slow, when two threads write at once, or when a request ID needs to appear on every line.

A good answer shows four things. First, a clean separation between deciding whether to log (levels, filters), shaping the output (formatters), and delivering it (appenders). Second, a Chain of Responsibility that lets one record flow through several handlers. Third, an honest treatment of async logging: a bounded queue, what to do when it's full, and how to shut down without losing the last lines. Fourth, a reasoned position on the Singleton question, because every logging library has a global entry point and every interviewer has an opinion about it.

Real libraries are excellent references here, and it's fine to cite them. Log4j 2, Logback (behind the SLF4J facade) and Python's logging module all converged on nearly the same shape. This page builds a small version of that shape from scratch, then compares it with theirs.

1. Clarifying questions and requirements

QuestionWhy it mattersAnswer we'll assume
Which levels? Can they be set per logger?Drives the Level type and level inheritanceTRACE, DEBUG, INFO, WARN, ERROR. Per-logger override, otherwise a root level
Where does output go?Number and kind of appendersConsole, file, size-rotated file, and an in-memory one for tests
Can one message go to several destinations with different rules?One sink or a pipelineYes: e.g. everything to console, WARN+ to a file
What format? Text, JSON?Formatter as a pluggable pieceText pattern now, JSON as an extension
Synchronous or asynchronous?Whether the caller's thread pays for I/OBoth. Async must be bounded
If the async queue fills up, block or drop?Back-pressure policyConfigurable. Never drop WARN and above
Do we need per-request context (request ID, user ID)?MDC, and how it crosses threadsYes
Multiple threads?Interleaved lines, appender safetyYes
Must logging ever crash the app?Error handling inside appendersNever. Failures go to stderr
Configuration from a file?A config parser, hot reloadOut of scope. Configure in code

Functional requirements

  1. logger.info("...") and friends at five levels, plus error(message, throwable).
  2. A record below the effective level is discarded before any formatting work.
  3. Expensive messages can be passed as a lambda and are only evaluated if enabled.
  4. Records pass through a configurable chain of handlers. A handler may write, filter, or forward.
  5. Appenders: console, plain file, size-based rotating file with N backups, in-memory.
  6. Formatters turn a record into a line. Timestamp, level, thread, logger name, message, context, stack trace.
  7. Context (MDC): key/value pairs set once per request and included automatically on every record.
  8. An async handler decouples callers from slow appenders, with a bounded queue and a choice of block or drop.
  9. shutdown() flushes everything that was accepted.

Non-functional requirements

  • Cheap when disabled. A disabled debug call should cost about one comparison.
  • Thread-safe. Lines never interleave mid-line, and appender state (file size, rotation) is never corrupted.
  • Bounded memory. No unbounded queue, ever.
  • Never throws into the caller. A full disk must not take down a payment request.
  • Testable. Clock and outputs are injectable, so tests assert on exact lines.

2. Entities

EntityResponsibility
LevelOrdered severity. atLeast(other) is the only operation that matters
LogRecordImmutable snapshot of one event: time, level, logger name, thread, message, context, error
LoggerThe API callers use. Checks the level, builds the record, hands it to the manager
LogManagerRegistry of named loggers, owns the root level and the handler chain, and the clock
HandlerOne link in the chain. Processes a record, then decides whether to pass it on
AppenderHandlerA handler that formats and writes if the record meets its own threshold
FilterHandlerA handler that can stop the chain (drop noise)
AsyncHandlerA handler that queues records for a background worker that runs a downstream chain
FormatterRecord → string. Stateless
AppenderString → destination. Owns the I/O resource
MdcPer-thread (or per-async-context) key/values

The split between Formatter and Appender is the one interviewers look for. What it looks like and where it goes change independently. You want JSON to the file and plain text to the console, and that's two formatters and two appenders, not four classes. Log4j calls the formatter a Layout, Logback calls it an Encoder/Layout, and Python calls it a Formatter. All three have it.

The split between Logger and Handler is the other one. A Logger is cheap and named after the code that uses it (com.shop.payments). Handlers are few and configured centrally. Many loggers share one chain.

3. Class diagram

classDiagram
    class Level {
        <<enumeration>>
        TRACE
        DEBUG
        INFO
        WARN
        ERROR
        +atLeast(other) boolean
    }
    class LogRecord {
        +time: Instant
        +level: Level
        +logger: String
        +thread: String
        +message: String
        +context: Map
        +error: Throwable
    }
    class LogManager {
        -loggers: Map of String to Logger
        -rootLevel: Level
        -chain: Handler
        -clock: Clock
        +global() LogManager
        +getLogger(name) Logger
        +configure(level, chain)
        +levelFor(name) Level
        +shutdown()
    }
    class Logger {
        -name: String
        -level: Level
        +isEnabled(level) boolean
        +info(message)
        +debug(supplier)
        +error(message, error)
    }
    class Handler {
        <<abstract>>
        -next: Handler
        +linkWith(next) Handler
        +handle(record)
        #process(record) boolean
        +close()
    }
    class AppenderHandler {
        -threshold: Level
        -formatter: Formatter
        -appender: Appender
    }
    class FilterHandler {
        -accept: Predicate
    }
    class AsyncHandler {
        -queue: BlockingQueue
        -downstream: Handler
        -overflow: Overflow
        -dropped: AtomicLong
    }
    class Formatter {
        <<interface>>
        +format(record) String
    }
    class PatternFormatter
    class Appender {
        <<interface>>
        +write(line)
        +close()
    }
    class ConsoleAppender
    class FileAppender
    class RotatingFileAppender {
        -maxBytes: long
        -backups: int
    }
    class MemoryAppender
    class Mdc {
        +put(key, value)
        +scoped(key, value) Scope
        +snapshot() Map
    }
    LogManager "1" o-- "*" Logger
    LogManager --> Handler : chain head
    Logger ..> LogRecord : creates
    Logger ..> Mdc : snapshots
    Handler --> Handler : next
    Handler <|-- AppenderHandler
    Handler <|-- FilterHandler
    Handler <|-- AsyncHandler
    AsyncHandler --> Handler : downstream
    AppenderHandler --> Formatter
    AppenderHandler --> Appender
    Formatter <|.. PatternFormatter
    Appender <|.. ConsoleAppender
    Appender <|.. FileAppender
    Appender <|.. RotatingFileAppender
    Appender <|.. MemoryAppender

The diagram shows two levels of filtering. Logger checks the effective level of the logger. Each AppenderHandler then checks its own threshold. That's how "DEBUG to console, WARN to file" works: the logger lets DEBUG through, the file handler ignores it.

4. Key flows

A synchronous log call

sequenceDiagram
    participant App
    participant L as Logger
    participant M as LogManager
    participant F as FilterHandler
    participant C as AppenderHandler console
    participant W as AppenderHandler file
    App->>L: warn("disk 91% full")
    L->>M: levelFor("app.disk")
    M-->>L: INFO
    L->>L: WARN at least INFO, build LogRecord with MDC snapshot
    L->>M: dispatch(record)
    M->>F: handle(record)
    F->>F: accept, not a healthcheck
    F->>C: handle(record)
    C->>C: WARN at least DEBUG, format and write
    C->>W: handle(record)
    W->>W: WARN at least WARN, format and write
    W-->>App: returns on the caller's thread

A disabled call costs one comparison

sequenceDiagram
    participant App
    participant L as Logger
    App->>L: debug(supplier of big string)
    L->>L: DEBUG is below INFO
    L-->>App: return, supplier never called

Async logging with back-pressure

sequenceDiagram
    participant T as App thread
    participant A as AsyncHandler
    participant Q as Bounded queue
    participant W as Worker thread
    participant D as Downstream chain
    T->>A: handle(INFO record)
    A->>Q: offer(record)
    alt queue has space
        Q-->>A: accepted
    else queue full and level below WARN
        A->>A: dropped++
    end
    T->>A: handle(ERROR record)
    A->>Q: put(record), blocks until space
    W->>Q: take()
    Q-->>W: record
    W->>D: handle(record)
    D->>D: format and write to file

AsyncHandler lifecycle

stateDiagram-v2
    [*] --> Running: constructed, worker started
    Running --> Running: records queued and drained
    Running --> Draining: close() sets closed, enqueues STOP
    Draining --> Stopped: worker reaches STOP, downstream closed
    Stopped --> [*]
    note right of Draining
        records accepted before STOP are still written
    end note

5. Patterns used, and the alternatives rejected

Chain of Responsibility for handlers

Each Handler holds a reference to the next one. handle(record) runs this handler's process, and if process returns true, passes the record on. The chain is built once at configuration time:

FilterHandler(drop healthchecks) -> AppenderHandler(DEBUG, console) -> AsyncHandler(file chain)

The classic GoF Chain of Responsibility stops at the first handler that "handles" the request, like a help desk escalating a ticket. Logging uses the pipeline variant: most handlers do their work and pass the record along anyway, so one record can reach several destinations. A handler can still stop the chain. FilterHandler does exactly that, and so does the rate-limiting filter in Extension B. Being able to explain that distinction is worth more than drawing the pattern.

Why a chain instead of a List<Handler> that the logger loops over? A list works, and Python's logging uses one (each logger has handlers, and records propagate up to parent loggers). The chain earns its keep when a handler needs to wrap what comes after it. AsyncHandler takes a whole downstream chain and runs it on another thread. A filter at the front can short-circuit everything. With a flat list, each of those becomes a special case in the loop. If the interviewer prefers a list, that's a fine design too. Say "list of handlers each with a filter" is the Python model, and the chain is closer to Log4j's filter/appender-ref model.

Rejected: if (level == ERROR) writeFile(); if (level >= DEBUG) writeConsole(); inside Logger. Every new destination edits the logger. That's the Open/Closed violation the pattern exists to remove.

Strategy for formatters and appenders

Formatter and Appender are both one-method interfaces with several interchangeable implementations: textbook Strategy. AppenderHandler composes one of each. Adding JSON output is a new formatter class. Adding Kafka output is a new appender class. Nothing else changes.

Rejected: an inheritance tree like JsonFileAppender extends FileAppender. The number of classes becomes formats × destinations.

Decorator, lightly

AsyncHandler wraps another handler and adds behaviour (moving work to another thread) without changing its interface. Extension C's RedactingFormatter wraps another formatter. Both are Decorators. You don't need to make a big deal of it, but naming it shows you see the shape.

Producer–consumer for async logging

Application threads produce records. One worker thread consumes them. A bounded BlockingQueue sits between. That's the classic producer–consumer arrangement covered in Concurrency Patterns in LLD. The design questions are all about the boundary:

  • Bounded, always. An unbounded queue turns a slow disk into an out-of-memory crash, which is much worse than slow logging.
  • What happens when it's full? Three options. Block the caller, which preserves every line but lets a slow disk slow down request handling. Drop the new record, which keeps the app fast but loses data. Drop the oldest, which keeps the most recent context. The design here makes it configurable, with a severity floor: records at WARN and above always block, so you never lose the error that explains the outage. Logback's AsyncAppender does almost exactly this. Its discardingThreshold drops TRACE/DEBUG/INFO once the queue is 80% full, and neverBlock switches blocking off entirely.
  • Shutdown. The worker must drain everything accepted before close() returns, or the last lines before a crash vanish. A poison pill (a sentinel record) placed at the back of the queue does this cleanly: everything ahead of it gets written.

The Singleton debate

Every logging library offers a global way in: LoggerFactory.getLogger(...) in SLF4J, LogManager.getLogger(...) in Log4j, logging.getLogger(...) in Python. Is that a Singleton, and is it bad?

The arguments for a global logging entry point are real. Logging is a genuine cross-cutting concern: nearly every class needs it, and threading a Logger parameter through every constructor in a codebase is noisy for no benefit. Configuration (handlers, levels) really is process-wide. And a logger has no effect on business results, so the usual Singleton harm (hidden coupling to mutable state that changes behaviour) is mostly absent.

The arguments against a hard Singleton are also real. A private constructor plus getInstance() makes it impossible to have two independent configurations, which is exactly what tests want. Tests that assert on log output then share global state and interfere with each other when run in parallel. And static initialization order bugs show up when a logger is configured in one static block and used in another.

The position this design takes is the one the real libraries take in practice: a well-known default instance, not an enforced single instance. LogManager has a public constructor. LogManager.global() returns a lazily created static default. Production code calls LogManager.global().getLogger(...). Tests create their own new LogManager(fixedClock) and assert on a MemoryAppender with no global state. That's the sentence to say in the interview: "I'd keep a global access point because logging is cross-cutting, but I won't make it impossible to construct a second one, because tests need that."

In Java the default instance is held in a static final field. The JVM's class-initialization guarantees make that thread-safe and lazy (it's created when LogManager is first used) without any double-checked locking.

Value object for the record

LogRecord is immutable and carries a copy of the MDC. This matters a lot for async logging. The worker thread that eventually formats the record has its own, different thread-local context. If the record held a reference to the live MDC map instead of a snapshot, it would print whatever the request thread had in its context by the time the worker got to it, which is usually the next request's ID. This is a classic production bug.

6. Complete implementation

Each listing is complete and runnable, and its main checks: level filtering, lazy messages, MDC, the filter short-circuit, exception formatting, file rotation, async delivery from eight concurrent threads with no lost or reordered lines per thread, and the drop policy that never drops errors.

// file: LoggingDemo.java
import java.io.*;
import java.nio.charset.StandardCharsets;
import java.nio.file.*;
import java.time.*;
import java.time.format.DateTimeFormatter;
import java.util.*;
import java.util.concurrent.*;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.concurrent.atomic.AtomicLong;
import java.util.function.Predicate;
import java.util.function.Supplier;

enum Level {
    TRACE, DEBUG, INFO, WARN, ERROR;
    boolean atLeast(Level other) { return compareTo(other) >= 0; }
}

record LogRecord(Instant time, Level level, String logger, String thread,
                 String message, Map<String, String> context, Throwable error) {}

/** Mapped Diagnostic Context: per-thread key/values copied into every record. */
final class Mdc {
    interface Scope extends AutoCloseable { @Override void close(); }

    private static final ThreadLocal<Map<String, String>> CTX = ThreadLocal.withInitial(HashMap::new);
    private Mdc() {}

    static void put(String key, String value) { CTX.get().put(key, Objects.requireNonNull(value)); }
    static void remove(String key) { CTX.get().remove(key); }
    static void clear() { CTX.remove(); }

    static Map<String, String> snapshot() {
        Map<String, String> m = CTX.get();
        return m.isEmpty() ? Map.of() : Map.copyOf(m);
    }

    /** try (var s = Mdc.scoped("requestId", id)) { ... } restores the previous value on exit. */
    static Scope scoped(String key, String value) {
        String previous = CTX.get().get(key);
        put(key, value);
        return () -> { if (previous == null) remove(key); else put(key, previous); };
    }
}

interface Formatter { String format(LogRecord r); }

final class PatternFormatter implements Formatter {
    private static final DateTimeFormatter TS = DateTimeFormatter.ISO_INSTANT; // immutable, thread-safe

    public String format(LogRecord r) {
        StringBuilder sb = new StringBuilder()
            .append(TS.format(r.time())).append(' ')
            .append(String.format("%-5s", r.level()))
            .append(" [").append(r.thread()).append("] ")
            .append(r.logger()).append(" - ").append(r.message());
        if (!r.context().isEmpty()) sb.append(' ').append(new TreeMap<>(r.context()));
        if (r.error() != null) {
            StringWriter trace = new StringWriter();
            r.error().printStackTrace(new PrintWriter(trace));
            sb.append('\n').append(trace.toString().stripTrailing());
        }
        return sb.toString();
    }
}

interface Appender extends AutoCloseable {
    void write(String line);
    @Override default void close() {}
}

final class ConsoleAppender implements Appender {
    private final PrintStream out;
    ConsoleAppender(PrintStream out) { this.out = out; }
    public void write(String line) { out.println(line); } // PrintStream locks internally
}

final class MemoryAppender implements Appender {
    private final ConcurrentLinkedQueue<String> lines = new ConcurrentLinkedQueue<>();
    public void write(String line) { lines.add(line); }
    List<String> lines() { return List.copyOf(lines); }
}

final class FileAppender implements Appender {
    private final OutputStream out;

    FileAppender(Path path) throws IOException {
        out = Files.newOutputStream(path, StandardOpenOption.CREATE, StandardOpenOption.APPEND);
    }

    public synchronized void write(String line) {
        try {
            out.write((line + "\n").getBytes(StandardCharsets.UTF_8));
            out.flush();
        } catch (IOException e) { throw new UncheckedIOException(e); }
    }

    public synchronized void close() {
        try { out.close(); } catch (IOException e) { throw new UncheckedIOException(e); }
    }
}

/** app.log rolls to app.log.1, app.log.1 to app.log.2, ..., keeping `backups` old files. */
final class RotatingFileAppender implements Appender {
    private final Path path;
    private final long maxBytes;
    private final int backups;
    private OutputStream out;
    private long size;

    RotatingFileAppender(Path path, long maxBytes, int backups) throws IOException {
        if (maxBytes < 1 || backups < 0) throw new IllegalArgumentException("bad rotation settings");
        this.path = path;
        this.maxBytes = maxBytes;
        this.backups = backups;
        this.size = Files.exists(path) ? Files.size(path) : 0;
        this.out = open();
    }

    private OutputStream open() throws IOException {
        return Files.newOutputStream(path, StandardOpenOption.CREATE, StandardOpenOption.APPEND);
    }

    private Path backup(int i) { return path.resolveSibling(path.getFileName() + "." + i); }

    public synchronized void write(String line) {
        byte[] bytes = (line + "\n").getBytes(StandardCharsets.UTF_8);
        try {
            if (size > 0 && size + bytes.length > maxBytes) rotate();
            out.write(bytes);
            out.flush();
            size += bytes.length;
        } catch (IOException e) { throw new UncheckedIOException(e); }
    }

    private void rotate() throws IOException {
        out.close();
        if (backups == 0) {
            Files.delete(path);
        } else {
            Files.deleteIfExists(backup(backups));
            for (int i = backups - 1; i >= 1; i--) {
                if (Files.exists(backup(i))) Files.move(backup(i), backup(i + 1));
            }
            Files.move(path, backup(1));
        }
        out = open();
        size = 0;
    }

    public synchronized void close() {
        try { out.close(); } catch (IOException e) { throw new UncheckedIOException(e); }
    }
}

/** One link in the chain. process() returns false to stop the record here. */
abstract class Handler {
    private Handler next;

    /** Links and returns `next`, so chains read left to right: a.linkWith(b).linkWith(c). */
    Handler linkWith(Handler next) { this.next = next; return next; }

    final void handle(LogRecord r) {
        boolean proceed = true;
        try {
            proceed = process(r);
        } catch (RuntimeException e) { // logging must never break the caller
            System.err.println("[logging] " + getClass().getSimpleName() + " failed: " + e);
        }
        if (proceed && next != null) next.handle(r);
    }

    protected abstract boolean process(LogRecord r);
    protected void closeSelf() {}

    final void close() {
        closeSelf();
        if (next != null) next.close();
    }
}

final class AppenderHandler extends Handler {
    private final Level threshold;
    private final Formatter formatter;
    private final Appender appender;

    AppenderHandler(Level threshold, Formatter formatter, Appender appender) {
        this.threshold = threshold;
        this.formatter = formatter;
        this.appender = appender;
    }

    protected boolean process(LogRecord r) {
        if (r.level().atLeast(threshold)) appender.write(formatter.format(r));
        return true;
    }

    @Override protected void closeSelf() { appender.close(); }
}

final class FilterHandler extends Handler {
    private final Predicate<LogRecord> accept;
    FilterHandler(Predicate<LogRecord> accept) { this.accept = accept; }
    protected boolean process(LogRecord r) { return accept.test(r); }
}

/** Producer-consumer: callers enqueue, one worker runs the downstream chain. */
final class AsyncHandler extends Handler {
    enum Overflow { BLOCK, DROP }

    private static final LogRecord STOP =
        new LogRecord(Instant.EPOCH, Level.ERROR, "", "", "STOP", Map.of(), null);

    private final BlockingQueue<LogRecord> queue;
    private final Handler downstream;
    private final Overflow overflow;
    private final Level neverDropAtOrAbove;
    private final AtomicLong dropped = new AtomicLong();
    private final Thread worker;
    private volatile boolean closed;

    AsyncHandler(Handler downstream, int capacity, Overflow overflow, Level neverDropAtOrAbove) {
        this.queue = new ArrayBlockingQueue<>(capacity);
        this.downstream = downstream;
        this.overflow = overflow;
        this.neverDropAtOrAbove = neverDropAtOrAbove;
        this.worker = new Thread(this::drain, "log-writer");
        worker.setDaemon(true);
        worker.start();
    }

    protected boolean process(LogRecord r) {
        if (closed) { dropped.incrementAndGet(); return true; }
        boolean mayDrop = overflow == Overflow.DROP && !r.level().atLeast(neverDropAtOrAbove);
        if (mayDrop) {
            if (!queue.offer(r)) dropped.incrementAndGet();
        } else {
            try {
                queue.put(r); // back-pressure: the caller waits for space
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
                dropped.incrementAndGet();
            }
        }
        return true;
    }

    private void drain() {
        try {
            while (true) {
                LogRecord r = queue.take();
                if (r == STOP) return;
                downstream.handle(r);
            }
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
    }

    long dropped() { return dropped.get(); }

    // Simplification: a record racing with close() can land after STOP and be skipped; fine at shutdown.
    @Override protected void closeSelf() {
        closed = true;
        try {
            queue.put(STOP);
            worker.join();
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
        downstream.close();
    }
}

final class Logger {
    private final String name;
    private final LogManager manager;
    private volatile Level level; // null: ask the manager

    Logger(String name, LogManager manager) { this.name = name; this.manager = manager; }

    String name() { return name; }
    void setLevel(Level level) { this.level = level; }

    boolean isEnabled(Level l) {
        Level own = level;
        return l.atLeast(own != null ? own : manager.levelFor(name));
    }

    void log(Level l, String message, Throwable error) {
        if (!isEnabled(l)) return;
        manager.dispatch(new LogRecord(manager.clock().instant(), l, name,
            Thread.currentThread().getName(), message, Mdc.snapshot(), error));
    }

    void log(Level l, Supplier<String> message) {
        if (isEnabled(l)) log(l, message.get(), null);
    }

    void trace(String m) { log(Level.TRACE, m, null); }
    void debug(String m) { log(Level.DEBUG, m, null); }
    void debug(Supplier<String> m) { log(Level.DEBUG, m); }
    void info(String m) { log(Level.INFO, m, null); }
    void warn(String m) { log(Level.WARN, m, null); }
    void error(String m) { log(Level.ERROR, m, null); }
    void error(String m, Throwable t) { log(Level.ERROR, m, t); }
}

/** A well-known default instance via global(), but tests can build their own. */
class LogManager {
    private static final LogManager GLOBAL = new LogManager(Clock.systemUTC());

    private final ConcurrentHashMap<String, Logger> loggers = new ConcurrentHashMap<>();
    private final Clock clock;
    private volatile Level rootLevel = Level.INFO;
    private volatile Handler chain; // null: discard everything

    LogManager(Clock clock) { this.clock = clock; }

    static LogManager global() { return GLOBAL; }

    Logger getLogger(String name) { return loggers.computeIfAbsent(name, n -> new Logger(n, this)); }

    void configure(Level rootLevel, Handler chain) {
        this.rootLevel = rootLevel;
        this.chain = chain;
    }

    /** Effective level for a logger without its own level. Overridable for hierarchies. */
    Level levelFor(String loggerName) { return rootLevel; }

    Clock clock() { return clock; }

    void dispatch(LogRecord r) {
        Handler h = chain;
        if (h != null) h.handle(r);
    }

    void shutdown() {
        Handler h = chain;
        chain = null;
        if (h != null) h.close();
    }
}

class LoggingDemo {
    static void check(boolean ok, String msg) { if (!ok) throw new AssertionError(msg); }

    public static void main(String[] args) throws Exception {
        Clock fixed = Clock.fixed(Instant.parse("2026-11-10T09:30:00Z"), ZoneOffset.UTC);
        Path dir = Files.createTempDirectory("logdemo");

        // 1. Sync chain: filter -> memory (DEBUG+) -> rotating file (WARN+).
        LogManager lm = new LogManager(fixed);
        MemoryAppender memory = new MemoryAppender();
        Path file = dir.resolve("app.log");
        Handler head = new FilterHandler(r -> !r.message().contains("healthcheck"));
        head.linkWith(new AppenderHandler(Level.DEBUG, new PatternFormatter(), memory))
            .linkWith(new AppenderHandler(Level.WARN, new PatternFormatter(),
                new RotatingFileAppender(file, 200, 2)));
        lm.configure(Level.INFO, head);

        Logger db = lm.getLogger("app.db");
        Logger web = lm.getLogger("app.web");
        db.setLevel(Level.DEBUG);
        check(lm.getLogger("app.db") == db, "loggers are cached by name");

        AtomicInteger built = new AtomicInteger();
        web.debug(() -> { built.incrementAndGet(); return "expensive"; });
        check(built.get() == 0, "disabled supplier must not run");
        db.debug(() -> { built.incrementAndGet(); return "query took 12ms"; });
        check(built.get() == 1, "enabled supplier runs once");

        web.info("GET /healthcheck");
        try (Mdc.Scope s = Mdc.scoped("requestId", "r-42")) {
            web.info("GET /orders");
        }
        web.info("after scope");
        web.error("payment failed", new IllegalStateException("card declined"));

        List<String> lines = memory.lines();
        check(lines.size() == 4, "expected 4 lines, got " + lines);
        check(lines.get(0).equals("2026-11-10T09:30:00Z DEBUG [main] app.db - query took 12ms"), lines.get(0));
        check(lines.get(1).endsWith("GET /orders {requestId=r-42}"), lines.get(1));
        check(!lines.get(2).contains("requestId"), "MDC must be restored after the scope");
        check(lines.get(3).contains("IllegalStateException: card declined"), "stack trace missing");

        for (int i = 0; i < 20; i++) web.warn("disk warning number " + i);
        lm.shutdown();
        check(Files.exists(dir.resolve("app.log.1")) && Files.exists(dir.resolve("app.log.2")), "backups");
        check(!Files.exists(dir.resolve("app.log.3")), "only two backups kept");
        for (String f : List.of("app.log", "app.log.1", "app.log.2")) {
            check(Files.size(dir.resolve(f)) <= 200, f + " exceeds maxBytes");
        }
        check(Files.readString(dir.resolve("app.log")).contains("number 19"), "newest line in app.log");

        asyncBlockingLosesNothing(fixed);
        asyncDropNeverDropsErrors(fixed);
        System.out.println("LoggingDemo: all checks passed");
    }

    static void asyncBlockingLosesNothing(Clock clock) throws Exception {
        LogManager lm = new LogManager(clock);
        MemoryAppender memory = new MemoryAppender();
        Formatter compact = r -> r.context().get("worker") + ":" + r.message();
        AsyncHandler async = new AsyncHandler(
            new AppenderHandler(Level.TRACE, compact, memory), 64, AsyncHandler.Overflow.BLOCK, Level.WARN);
        lm.configure(Level.INFO, async);
        Logger log = lm.getLogger("load");
        int threads = 8, perThread = 5_000;
        ExecutorService pool = Executors.newFixedThreadPool(threads);
        CountDownLatch start = new CountDownLatch(1);
        List<Future<Object>> fs = new ArrayList<>();
        for (int t = 0; t < threads; t++) {
            final String id = "w" + t;
            fs.add(pool.submit(() -> {
                start.await();
                try (Mdc.Scope s = Mdc.scoped("worker", id)) {
                    for (int i = 0; i < perThread; i++) log.info(Integer.toString(i));
                }
                return null;
            }));
        }
        start.countDown();
        for (Future<Object> f : fs) f.get();
        pool.shutdown();
        lm.shutdown(); // drains the queue
        List<String> lines = memory.lines();
        check(lines.size() == threads * perThread, "lost lines: " + lines.size());
        Map<String, Integer> lastSeen = new HashMap<>();
        for (String line : lines) {
            String[] parts = line.split(":");
            int n = Integer.parseInt(parts[1]);
            int prev = lastSeen.getOrDefault(parts[0], -1);
            check(n == prev + 1, "per-thread order broken for " + parts[0]);
            lastSeen.put(parts[0], n);
        }
        check(async.dropped() == 0, "BLOCK must not drop");
    }

    static void asyncDropNeverDropsErrors(Clock clock) {
        LogManager lm = new LogManager(clock);
        MemoryAppender memory = new MemoryAppender();
        Appender slow = new Appender() {
            public void write(String line) {
                try { Thread.sleep(1); } catch (InterruptedException e) { Thread.currentThread().interrupt(); }
                memory.write(line);
            }
        };
        AsyncHandler async = new AsyncHandler(
            new AppenderHandler(Level.TRACE, LogRecord::message, slow), 8,
            AsyncHandler.Overflow.DROP, Level.WARN);
        lm.configure(Level.INFO, async);
        Logger log = lm.getLogger("burst");
        for (int i = 0; i < 200; i++) {
            log.info("info " + i);
            if (i % 10 == 0) log.error("error " + i);
        }
        lm.shutdown();
        List<String> lines = memory.lines();
        long errors = lines.stream().filter(l -> l.startsWith("error")).count();
        check(errors == 20, "an ERROR was dropped");
        check(async.dropped() > 0, "a burst into a tiny queue should drop some INFO");
        check(lines.size() + async.dropped() == 220, "every record is written or counted as dropped");
    }
}
# file: logkit.py
"""A small logging framework: levels, handler chain, appenders, MDC, async."""
from __future__ import annotations

import contextlib
import contextvars
import datetime as dt
import os
import queue
import sys
import tempfile
import threading
import time
import traceback
from abc import ABC, abstractmethod
from dataclasses import dataclass
from enum import IntEnum
from types import MappingProxyType
from typing import Callable, Dict, Iterator, List, Mapping, Optional, TextIO, Union

Clock = Callable[[], dt.datetime]


def utc_now() -> dt.datetime:
    return dt.datetime.now(dt.timezone.utc)


class Level(IntEnum):
    TRACE = 5
    DEBUG = 10
    INFO = 20
    WARN = 30
    ERROR = 40


@dataclass(frozen=True)
class LogRecord:
    time: dt.datetime
    level: Level
    logger: str
    thread: str
    message: str
    context: Mapping[str, str]
    error: Optional[BaseException] = None


# MDC: a ContextVar follows the current thread *and* the current asyncio task.
_EMPTY: Mapping[str, str] = MappingProxyType({})
_mdc: contextvars.ContextVar[Mapping[str, str]] = contextvars.ContextVar("mdc", default=_EMPTY)


@contextlib.contextmanager
def mdc(**values: str) -> Iterator[None]:
    token = _mdc.set(MappingProxyType({**_mdc.get(), **values}))  # immutable, so snapshots are free
    try:
        yield
    finally:
        _mdc.reset(token)


class Formatter(ABC):
    @abstractmethod
    def format(self, r: LogRecord) -> str: ...


class PatternFormatter(Formatter):
    def format(self, r: LogRecord) -> str:
        stamp = r.time.astimezone(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
        line = f"{stamp} {r.level.name:<5} [{r.thread}] {r.logger} - {r.message}"
        if r.context:
            line += " {" + ", ".join(f"{k}={v}" for k, v in sorted(r.context.items())) + "}"
        if r.error is not None:
            tb = "".join(traceback.format_exception(r.error)).rstrip()
            line += "\n" + tb
        return line


class MessageOnly(Formatter):
    def format(self, r: LogRecord) -> str:
        return r.message


class Appender(ABC):
    @abstractmethod
    def write(self, line: str) -> None: ...

    def close(self) -> None:
        pass


class ConsoleAppender(Appender):
    def __init__(self, stream: TextIO = sys.stdout) -> None:
        self._stream = stream
        self._lock = threading.Lock()

    def write(self, line: str) -> None:
        with self._lock:  # one write per line, so lines never interleave
            self._stream.write(line + "\n")
            self._stream.flush()


class MemoryAppender(Appender):
    def __init__(self) -> None:
        self._lines: List[str] = []
        self._lock = threading.Lock()

    def write(self, line: str) -> None:
        with self._lock:
            self._lines.append(line)

    def lines(self) -> List[str]:
        with self._lock:
            return list(self._lines)


class FileAppender(Appender):
    def __init__(self, path: Union[str, os.PathLike]) -> None:
        self._file = open(path, "ab")
        self._lock = threading.Lock()

    def write(self, line: str) -> None:
        with self._lock:
            self._file.write((line + "\n").encode("utf-8"))
            self._file.flush()

    def close(self) -> None:
        with self._lock:
            self._file.close()


class RotatingFileAppender(Appender):
    """app.log -> app.log.1 -> app.log.2 ..., keeping `backups` old files."""

    def __init__(self, path: str, max_bytes: int, backups: int) -> None:
        if max_bytes < 1 or backups < 0:
            raise ValueError("bad rotation settings")
        self._path, self._max, self._backups = path, max_bytes, backups
        self._lock = threading.Lock()
        self._size = os.path.getsize(path) if os.path.exists(path) else 0
        self._file = open(path, "ab")

    def write(self, line: str) -> None:
        data = (line + "\n").encode("utf-8")
        with self._lock:
            if self._size > 0 and self._size + len(data) > self._max:
                self._rotate()
            self._file.write(data)
            self._file.flush()
            self._size += len(data)

    def _rotate(self) -> None:
        self._file.close()
        if self._backups == 0:
            os.remove(self._path)
        else:
            for i in range(self._backups - 1, 0, -1):
                src = f"{self._path}.{i}"
                if os.path.exists(src):
                    os.replace(src, f"{self._path}.{i + 1}")  # replace overwrites the oldest
            os.replace(self._path, f"{self._path}.1")
        self._file = open(self._path, "ab")
        self._size = 0

    def close(self) -> None:
        with self._lock:
            self._file.close()


class Handler(ABC):
    """One link in the chain. process() returns False to stop the record."""

    def __init__(self) -> None:
        self._next: Optional[Handler] = None

    def link_with(self, nxt: "Handler") -> "Handler":
        self._next = nxt
        return nxt

    def handle(self, r: LogRecord) -> None:
        proceed = True
        try:
            proceed = self.process(r)
        except Exception as e:  # logging must never break the caller
            print(f"[logging] {type(self).__name__} failed: {e!r}", file=sys.stderr)
        if proceed and self._next is not None:
            self._next.handle(r)

    @abstractmethod
    def process(self, r: LogRecord) -> bool: ...

    def close_self(self) -> None:
        pass

    def close(self) -> None:
        self.close_self()
        if self._next is not None:
            self._next.close()


class AppenderHandler(Handler):
    def __init__(self, threshold: Level, formatter: Formatter, appender: Appender) -> None:
        super().__init__()
        self._threshold, self._formatter, self._appender = threshold, formatter, appender

    def process(self, r: LogRecord) -> bool:
        if r.level >= self._threshold:
            self._appender.write(self._formatter.format(r))
        return True

    def close_self(self) -> None:
        self._appender.close()


class FilterHandler(Handler):
    def __init__(self, accept: Callable[[LogRecord], bool]) -> None:
        super().__init__()
        self._accept = accept

    def process(self, r: LogRecord) -> bool:
        return self._accept(r)


class AsyncHandler(Handler):
    """Producer-consumer: callers enqueue, one worker thread runs the downstream chain."""

    BLOCK, DROP = "block", "drop"
    _STOP = object()

    def __init__(self, downstream: Handler, capacity: int, overflow: str = BLOCK,
                 never_drop_at_or_above: Level = Level.WARN) -> None:
        super().__init__()
        self._queue: "queue.Queue[object]" = queue.Queue(maxsize=capacity)
        self._downstream = downstream
        self._overflow = overflow
        self._floor = never_drop_at_or_above
        self._dropped = 0
        self._dropped_lock = threading.Lock()
        self._closed = False
        self._worker = threading.Thread(target=self._drain, name="log-writer", daemon=True)
        self._worker.start()

    def _drop(self) -> None:
        with self._dropped_lock:
            self._dropped += 1

    @property
    def dropped(self) -> int:
        with self._dropped_lock:
            return self._dropped

    def process(self, r: LogRecord) -> bool:
        if self._closed:
            self._drop()
        elif self._overflow == self.DROP and r.level < self._floor:
            try:
                self._queue.put_nowait(r)
            except queue.Full:
                self._drop()
        else:
            self._queue.put(r)  # back-pressure: wait for space
        return True

    def _drain(self) -> None:
        while True:
            item = self._queue.get()
            if item is self._STOP:
                return
            assert isinstance(item, LogRecord)
            self._downstream.handle(item)

    def close_self(self) -> None:
        self._closed = True
        self._queue.put(self._STOP)
        self._worker.join()
        self._downstream.close()


class Logger:
    def __init__(self, name: str, manager: "LogManager") -> None:
        self.name = name
        self._manager = manager
        self.level: Optional[Level] = None  # None: ask the manager

    def is_enabled(self, level: Level) -> bool:
        own = self.level
        return level >= (own if own is not None else self._manager.level_for(self.name))

    def log(self, level: Level, message: Union[str, Callable[[], str]],
            error: Optional[BaseException] = None) -> None:
        if not self.is_enabled(level):
            return
        text = message() if callable(message) else message
        self._manager.dispatch(LogRecord(self._manager.clock(), level, self.name,
                                         threading.current_thread().name, text, _mdc.get(), error))

    def trace(self, m: Union[str, Callable[[], str]]) -> None: self.log(Level.TRACE, m)
    def debug(self, m: Union[str, Callable[[], str]]) -> None: self.log(Level.DEBUG, m)
    def info(self, m: Union[str, Callable[[], str]]) -> None: self.log(Level.INFO, m)
    def warn(self, m: Union[str, Callable[[], str]]) -> None: self.log(Level.WARN, m)

    def error(self, m: Union[str, Callable[[], str]], error: Optional[BaseException] = None) -> None:
        self.log(Level.ERROR, m, error)


class LogManager:
    """A well-known default via LogManager.default(), but tests can build their own."""

    _default: Optional["LogManager"] = None
    _default_lock = threading.Lock()

    def __init__(self, clock: Clock = utc_now) -> None:
        self.clock = clock
        self.root_level = Level.INFO
        self._chain: Optional[Handler] = None
        self._loggers: Dict[str, Logger] = {}
        self._lock = threading.Lock()

    @classmethod
    def default(cls) -> "LogManager":
        with cls._default_lock:
            if cls._default is None:
                cls._default = cls()
            return cls._default

    def get_logger(self, name: str) -> Logger:
        with self._lock:
            if name not in self._loggers:
                self._loggers[name] = Logger(name, self)
            return self._loggers[name]

    def configure(self, root_level: Level, chain: Optional[Handler]) -> None:
        self.root_level, self._chain = root_level, chain

    def level_for(self, logger_name: str) -> Level:
        return self.root_level  # overridable for hierarchies

    def dispatch(self, r: LogRecord) -> None:
        chain = self._chain
        if chain is not None:
            chain.handle(r)

    def shutdown(self) -> None:
        chain, self._chain = self._chain, None
        if chain is not None:
            chain.close()


def _async_blocking_loses_nothing(clock: Clock) -> None:
    lm = LogManager(clock)
    memory = MemoryAppender()

    class Compact(Formatter):
        def format(self, r: LogRecord) -> str:
            return f"{r.context['worker']}:{r.message}"

    handler = AsyncHandler(AppenderHandler(Level.TRACE, Compact(), memory), 64, AsyncHandler.BLOCK)
    lm.configure(Level.INFO, handler)
    log = lm.get_logger("load")
    start = threading.Barrier(8)

    def worker(wid: str) -> None:
        start.wait()
        with mdc(worker=wid):
            for i in range(2_000):
                log.info(str(i))

    threads = [threading.Thread(target=worker, args=(f"w{t}",)) for t in range(8)]
    for t in threads:
        t.start()
    for t in threads:
        t.join()
    lm.shutdown()
    lines = memory.lines()
    assert len(lines) == 8 * 2_000, f"lost lines: {len(lines)}"
    last: Dict[str, int] = {}
    for line in lines:
        wid, n = line.split(":")
        assert int(n) == last.get(wid, -1) + 1, f"order broken for {wid}"
        last[wid] = int(n)
    assert handler.dropped == 0


def _async_drop_never_drops_errors(clock: Clock) -> None:
    lm = LogManager(clock)
    memory = MemoryAppender()

    class Slow(Appender):
        def write(self, line: str) -> None:
            time.sleep(0.001)
            memory.write(line)

    handler = AsyncHandler(AppenderHandler(Level.TRACE, MessageOnly(), Slow()), 8, AsyncHandler.DROP)
    lm.configure(Level.INFO, handler)
    log = lm.get_logger("burst")
    for i in range(200):
        log.info(f"info {i}")
        if i % 10 == 0:
            log.error(f"error {i}")
    lm.shutdown()
    lines = memory.lines()
    assert sum(1 for l in lines if l.startswith("error")) == 20, "an ERROR was dropped"
    assert handler.dropped > 0, "a burst into a tiny queue should drop some INFO"
    assert len(lines) + handler.dropped == 220


def main() -> None:
    fixed = dt.datetime(2026, 11, 10, 9, 30, tzinfo=dt.timezone.utc)
    clock: Clock = lambda: fixed
    tmp = tempfile.mkdtemp(prefix="logdemo")
    path = os.path.join(tmp, "app.log")

    lm = LogManager(clock)
    memory = MemoryAppender()
    head = FilterHandler(lambda r: "healthcheck" not in r.message)
    head.link_with(AppenderHandler(Level.DEBUG, PatternFormatter(), memory)).link_with(
        AppenderHandler(Level.WARN, PatternFormatter(), RotatingFileAppender(path, 200, 2)))
    lm.configure(Level.INFO, head)

    db, web = lm.get_logger("app.db"), lm.get_logger("app.web")
    db.level = Level.DEBUG
    assert lm.get_logger("app.db") is db

    calls = []
    web.debug(lambda: calls.append(1) or "expensive")
    assert calls == [], "disabled callable must not run"
    db.debug(lambda: calls.append(1) or "query took 12ms")
    assert calls == [1]

    web.info("GET /healthcheck")
    with mdc(requestId="r-42"):
        web.info("GET /orders")
    web.info("after scope")
    try:
        raise RuntimeError("card declined")
    except RuntimeError as e:
        web.error("payment failed", e)

    lines = memory.lines()
    assert len(lines) == 4, lines
    assert lines[0] == "2026-11-10T09:30:00Z DEBUG [MainThread] app.db - query took 12ms", lines[0]
    assert lines[1].endswith("GET /orders {requestId=r-42}"), lines[1]
    assert "requestId" not in lines[2]
    assert "RuntimeError: card declined" in lines[3]

    for i in range(20):
        web.warn(f"disk warning number {i}")
    lm.shutdown()
    assert os.path.exists(path + ".1") and os.path.exists(path + ".2")
    assert not os.path.exists(path + ".3")
    for f in (path, path + ".1", path + ".2"):
        assert os.path.getsize(f) <= 200, f
    with open(path, encoding="utf-8") as fh:
        assert "number 19" in fh.read()

    _async_blocking_loses_nothing(clock)
    _async_drop_never_drops_errors(clock)
    print("logkit.py: all checks passed")


if __name__ == "__main__":
    main()
// file: logkit.ts
// A small logging framework for Node: levels, handler chain, appenders, MDC, async.
// Run directly: npx tsx logkit.ts
import { AsyncLocalStorage } from "node:async_hooks";
import * as fs from "node:fs";
import * as os from "node:os";
import * as path from "node:path";

export enum Level { TRACE = 5, DEBUG = 10, INFO = 20, WARN = 30, ERROR = 40 }

export interface LogRecord {
  readonly time: Date;
  readonly level: Level;
  readonly logger: string;
  readonly message: string;
  readonly context: Readonly<Record<string, string>>;
  readonly error?: Error;
}

// MDC: AsyncLocalStorage follows a request across awaits, timers and callbacks.
const mdcStore = new AsyncLocalStorage<Readonly<Record<string, string>>>();
const EMPTY: Readonly<Record<string, string>> = Object.freeze({});

export function withContext<T>(values: Record<string, string>, fn: () => T): T {
  return mdcStore.run(Object.freeze({ ...(mdcStore.getStore() ?? EMPTY), ...values }), fn);
}

export interface Formatter { format(r: LogRecord): string; }

export class PatternFormatter implements Formatter {
  format(r: LogRecord): string {
    const stamp = r.time.toISOString().replace(/\.\d{3}Z$/, "Z");
    let line = `${stamp} ${Level[r.level].padEnd(5)} ${r.logger} - ${r.message}`;
    const keys = Object.keys(r.context).sort();
    if (keys.length) line += " {" + keys.map((k) => `${k}=${r.context[k]}`).join(", ") + "}";
    if (r.error) line += "\n" + (r.error.stack ?? String(r.error));
    return line;
  }
}

export interface Appender { write(line: string): void; close?(): void; }

export class ConsoleAppender implements Appender {
  write(line: string): void { process.stdout.write(line + "\n"); }
}

export class MemoryAppender implements Appender {
  readonly lines: string[] = [];
  write(line: string): void { this.lines.push(line); }
}

export class FileAppender implements Appender {
  private readonly fd: number;
  constructor(file: string) { this.fd = fs.openSync(file, "a"); }
  write(line: string): void { fs.writeSync(this.fd, line + "\n"); }
  close(): void { fs.closeSync(this.fd); }
}

/** app.log -> app.log.1 -> app.log.2 ..., keeping `backups` old files. */
export class RotatingFileAppender implements Appender {
  private fd: number;
  private size: number;

  constructor(private readonly file: string, private readonly maxBytes: number, private readonly backups: number) {
    if (maxBytes < 1 || backups < 0) throw new RangeError("bad rotation settings");
    this.size = fs.existsSync(file) ? fs.statSync(file).size : 0;
    this.fd = fs.openSync(file, "a");
  }

  write(line: string): void {
    const data = Buffer.from(line + "\n", "utf8");
    if (this.size > 0 && this.size + data.length > this.maxBytes) this.rotate();
    fs.writeSync(this.fd, data);
    this.size += data.length;
  }

  private rotate(): void {
    fs.closeSync(this.fd);
    if (this.backups === 0) {
      fs.rmSync(this.file);
    } else {
      for (let i = this.backups - 1; i >= 1; i--) {
        const src = `${this.file}.${i}`;
        if (fs.existsSync(src)) fs.renameSync(src, `${this.file}.${i + 1}`);
      }
      fs.renameSync(this.file, `${this.file}.1`);
    }
    this.fd = fs.openSync(this.file, "a");
    this.size = 0;
  }

  close(): void { fs.closeSync(this.fd); }
}

/** One link in the chain. process() returns false to stop the record here. */
export abstract class Handler {
  private next: Handler | null = null;

  linkWith<H extends Handler>(next: H): H { this.next = next; return next; }

  handle(r: LogRecord): void {
    let proceed = true;
    try {
      proceed = this.process(r);
    } catch (e) { // logging must never break the caller
      process.stderr.write(`[logging] ${this.constructor.name} failed: ${String(e)}\n`);
    }
    if (proceed && this.next) this.next.handle(r);
  }

  protected abstract process(r: LogRecord): boolean;
  protected async closeSelf(): Promise<void> {}

  async close(): Promise<void> {
    await this.closeSelf();
    if (this.next) await this.next.close();
  }
}

export class AppenderHandler extends Handler {
  constructor(private readonly threshold: Level, private readonly formatter: Formatter,
              private readonly appender: Appender) { super(); }

  protected process(r: LogRecord): boolean {
    if (r.level >= this.threshold) this.appender.write(this.formatter.format(r));
    return true;
  }

  protected async closeSelf(): Promise<void> { this.appender.close?.(); }
}

export class FilterHandler extends Handler {
  constructor(private readonly accept: (r: LogRecord) => boolean) { super(); }
  protected process(r: LogRecord): boolean { return this.accept(r); }
}

export type Overflow = "drop-newest" | "drop-oldest";

/**
 * Node can't block a synchronous log() call, so overflow means dropping.
 * Records at or above `neverDropAtOrAbove` are always kept, even past capacity.
 */
export class AsyncHandler extends Handler {
  private queue: LogRecord[] = [];
  private scheduled = false;
  private idle: Array<() => void> = [];
  dropped = 0;

  constructor(private readonly downstream: Handler, private readonly capacity: number,
              private readonly overflow: Overflow = "drop-newest",
              private readonly neverDropAtOrAbove: Level = Level.WARN) { super(); }

  protected process(r: LogRecord): boolean {
    if (this.queue.length >= this.capacity && r.level < this.neverDropAtOrAbove) {
      if (this.overflow === "drop-newest") { this.dropped++; return true; }
      const victim = this.queue.findIndex((q) => q.level < this.neverDropAtOrAbove);
      if (victim < 0) { this.dropped++; return true; }
      this.queue.splice(victim, 1);
      this.dropped++;
    }
    this.queue.push(r);
    this.schedule();
    return true;
  }

  private schedule(): void {
    if (this.scheduled) return;
    this.scheduled = true;
    setImmediate(() => this.drainBatch());
  }

  private drainBatch(): void {
    this.scheduled = false;
    const batch = this.queue.splice(0, 256); // bounded slice so I/O doesn't starve the event loop
    for (const r of batch) this.downstream.handle(r);
    if (this.queue.length) this.schedule();
    else this.idle.splice(0).forEach((resolve) => resolve());
  }

  flush(): Promise<void> {
    if (!this.queue.length && !this.scheduled) return Promise.resolve();
    return new Promise((resolve) => this.idle.push(resolve));
  }

  protected async closeSelf(): Promise<void> {
    await this.flush();
    await this.downstream.close();
  }
}

export type Clock = () => Date;

export class Logger {
  level: Level | undefined; // undefined: ask the manager
  constructor(readonly name: string, private readonly manager: LogManager) {}

  isEnabled(level: Level): boolean { return level >= (this.level ?? this.manager.levelFor(this.name)); }

  log(level: Level, message: string | (() => string), error?: Error): void {
    if (!this.isEnabled(level)) return;
    const text = typeof message === "function" ? message() : message;
    this.manager.dispatch({ time: this.manager.clock(), level, logger: this.name, message: text,
      context: mdcStore.getStore() ?? EMPTY, error });
  }

  trace(m: string | (() => string)): void { this.log(Level.TRACE, m); }
  debug(m: string | (() => string)): void { this.log(Level.DEBUG, m); }
  info(m: string | (() => string)): void { this.log(Level.INFO, m); }
  warn(m: string | (() => string)): void { this.log(Level.WARN, m); }
  error(m: string | (() => string), error?: Error): void { this.log(Level.ERROR, m, error); }
}

/** A well-known default via LogManager.default, but tests can build their own. */
export class LogManager {
  private static instance: LogManager | undefined;
  static get default(): LogManager { return (LogManager.instance ??= new LogManager()); }

  rootLevel = Level.INFO;
  private chain: Handler | null = null;
  private readonly loggers = new Map<string, Logger>();

  constructor(readonly clock: Clock = () => new Date()) {}

  getLogger(name: string): Logger {
    let logger = this.loggers.get(name);
    if (!logger) { logger = new Logger(name, this); this.loggers.set(name, logger); }
    return logger;
  }

  configure(rootLevel: Level, chain: Handler | null): void { this.rootLevel = rootLevel; this.chain = chain; }
  levelFor(_loggerName: string): Level { return this.rootLevel; } // overridable for hierarchies
  dispatch(r: LogRecord): void { this.chain?.handle(r); }

  async shutdown(): Promise<void> {
    const chain = this.chain;
    this.chain = null;
    if (chain) await chain.close();
  }
}

function assert(cond: unknown, msg: string): asserts cond { if (!cond) throw new Error(msg); }
const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));

async function main(): Promise<void> {
  const fixed = new Date("2026-11-10T09:30:00Z");
  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "logdemo"));
  const file = path.join(dir, "app.log");

  const lm = new LogManager(() => fixed);
  const memory = new MemoryAppender();
  const head = new FilterHandler((r) => !r.message.includes("healthcheck"));
  head.linkWith(new AppenderHandler(Level.DEBUG, new PatternFormatter(), memory))
    .linkWith(new AppenderHandler(Level.WARN, new PatternFormatter(), new RotatingFileAppender(file, 200, 2)));
  lm.configure(Level.INFO, head);

  const db = lm.getLogger("app.db");
  const web = lm.getLogger("app.web");
  db.level = Level.DEBUG;
  assert(lm.getLogger("app.db") === db, "loggers cached");

  let built = 0;
  const timesBuilt = (): number => built; // a call, so TS doesn't narrow it to a literal
  web.debug(() => { built++; return "expensive"; });
  assert(timesBuilt() === 0, "disabled callback must not run");
  db.debug(() => { built++; return "query took 12ms"; });
  assert(timesBuilt() === 1, "enabled callback runs once");

  web.info("GET /healthcheck");
  withContext({ requestId: "r-42" }, () => web.info("GET /orders"));
  web.info("after scope");
  web.error("payment failed", new Error("card declined"));

  assert(memory.lines.length === 4, `expected 4 lines, got ${memory.lines.length}`);
  assert(memory.lines[0] === "2026-11-10T09:30:00Z DEBUG app.db - query took 12ms", memory.lines[0]);
  assert(memory.lines[1].endsWith("GET /orders {requestId=r-42}"), memory.lines[1]);
  assert(!memory.lines[2].includes("requestId"), "context must not leak out of the scope");
  assert(memory.lines[3].includes("Error: card declined"), "stack trace missing");

  for (let i = 0; i < 20; i++) web.warn(`disk warning number ${i}`);
  await lm.shutdown();
  assert(fs.existsSync(`${file}.1`) && fs.existsSync(`${file}.2`) && !fs.existsSync(`${file}.3`), "backups");
  for (const f of [file, `${file}.1`, `${file}.2`]) assert(fs.statSync(f).size <= 200, `${f} too big`);
  assert(fs.readFileSync(file, "utf8").includes("number 19"), "newest line in app.log");

  // Concurrency in Node: 50 interleaved async "requests" must each keep their own context.
  const lm2 = new LogManager(() => fixed);
  const mem2 = new MemoryAppender();
  const compact: Formatter = { format: (r) => `${r.context.requestId}:${r.message}` };
  const async2 = new AsyncHandler(new AppenderHandler(Level.TRACE, compact, mem2), 10_000);
  lm2.configure(Level.INFO, async2);
  const log = lm2.getLogger("req");
  await Promise.all(Array.from({ length: 50 }, (_, i) => withContext({ requestId: `r${i}` }, async () => {
    for (let step = 0; step < 20; step++) {
      log.info(`r${i}`);
      await sleep(Math.random() * 2); // other requests run here
    }
  })));
  await lm2.shutdown();
  assert(mem2.lines.length === 1_000, "lost lines");
  assert(mem2.lines.every((l) => { const [ctx, msg] = l.split(":"); return ctx === msg; }), "context leaked");

  // Drop policy: a burst past capacity drops INFO but never ERROR.
  const lm3 = new LogManager(() => fixed);
  const mem3 = new MemoryAppender();
  const async3 = new AsyncHandler(new AppenderHandler(Level.TRACE, { format: (r) => r.message }, mem3), 8);
  lm3.configure(Level.INFO, async3);
  const burst = lm3.getLogger("burst");
  for (let i = 0; i < 200; i++) {
    burst.info(`info ${i}`);
    if (i % 10 === 0) burst.error(`error ${i}`);
  }
  await lm3.shutdown();
  assert(mem3.lines.filter((l) => l.startsWith("error")).length === 20, "an ERROR was dropped");
  assert(async3.dropped > 0 && mem3.lines.length + async3.dropped === 220, "drop accounting");

  console.log("logkit.ts: all checks passed");
}

if (require.main === module) {
  main().catch((e) => { console.error(e); process.exit(1); });
}

Walking through the code

Level check before anything else. Logger.log checks isEnabled before reading the clock, snapshotting the MDC or allocating a record. In a hot loop with DEBUG disabled, that's the difference between one comparison and several allocations. The lambda overloads go one step further: debug(() -> "rows=" + dumpRows()) never calls dumpRows() when DEBUG is off. SLF4J gets a similar benefit with parameterized messages: log.debug("rows={}", rows) defers the string concatenation until after the level check.

Two thresholds. The logger's level is "is anyone interested in DEBUG from app.db?" The handler's threshold is "does this destination want it?" Merging them into one would force a choice between a noisy file and a silent console.

Handler.handle is final, process is abstract. The chain-walking and the error handling live in one place. Subclasses can't forget to call next, and they can't let an exception escape. (That's a small Template Method.)

Formatters are stateless. DateTimeFormatter is immutable and thread-safe. The old SimpleDateFormat is not, and a shared one in a logging formatter is a well-known source of garbled timestamps under load.

Rotation is size-based and synchronous. The appender holds its own lock across "check size, maybe rotate, write". Without the lock, two threads can both decide to rotate, and the second rename moves the file the first one just created. Time-based rotation (daily files) is the same structure with a different trigger.

In TypeScript, async can't block. A synchronous log() call in Node cannot wait for queue space without freezing the event loop, which would also freeze the very drain that frees the space. So the Node AsyncHandler offers two drop policies, keeps WARN+ even past capacity (a soft bound with a documented exception), and exposes flush() as a promise. The worker is a setImmediate batch rather than a thread.

7. Concurrency

What's shared

StateWho touches itProtection
Logger registryAny thread calling getLoggerConcurrentHashMap.computeIfAbsent (Java), a lock (Python)
Root level, chain headRead on every call, written at configure timevolatile reads, no lock on the hot path
A logger's own levelRead on every callvolatile
Appender state: file handle, byte countEvery writing thread, or the one async workersynchronized / a lock per appender
The async queueAll producers, one consumerArrayBlockingQueue / queue.Queue are thread-safe
Drop counterProducersAtomicLong / a small lock
MDCOnly the owning threadThreadLocal / ContextVar, so no sharing at all

The hot path takes no lock

A disabled call reads two volatile fields and returns. An enabled synchronous call takes exactly one lock, inside the appender, for the duration of one write. That's why each appender locks itself instead of the whole chain sharing one lock: a slow file appender shouldn't block a console appender on another chain.

Why lines never interleave

Each appender writes a whole line, including the newline, inside its lock (or as one write call). Two threads can't produce INFO req-1 INFO req-2 ... .... Under async logging the question disappears entirely: there's exactly one writer thread.

Per-thread order is preserved, global order is not

With one async worker and a FIFO queue, records from one thread appear in the order that thread logged them. That's what the eight-thread test checks. Records from different threads appear in queue-arrival order, which may differ from timestamp order by a few microseconds. If a total order matters, sort by timestamp downstream. Don't serialize the producers to get it.

MDC across threads

ThreadLocal context doesn't follow work to another thread. If a request handler submits a task to an executor, the task runs with the pool thread's context, which is empty or, worse, left over from a previous task. Two rules handle this:

  1. Always clear or restore. Mdc.scoped in a try-with-resources (Java) or with mdc(...) (Python) guarantees restoration even when exceptions fly. Pool threads are reused, so a forgotten put leaks into the next request.
  2. Copy context on hand-off. Wrap tasks: capture Mdc.snapshot() when submitting, install it when the task starts, and clear it when it ends. Logback's MDC.getCopyOfContextMap()/setContextMap() exist for exactly this.

Python's contextvars and Node's AsyncLocalStorage are better here. They follow await boundaries automatically, so concurrent async requests on one thread each see their own context. The TypeScript test runs 50 interleaved requests and checks that no line carries another request's ID. Note that a new threading.Thread in Python starts with an empty context unless you run its target via contextvars.copy_context().run(...).

Shutdown ordering

LogManager.shutdown() swaps the chain out first (new calls become no-ops) and then closes it. AsyncHandler.close enqueues the poison pill, which goes behind every record already accepted, then joins the worker. A producer racing with shutdown can still slip a record in after the pill. That's acceptable at process exit and documented in a code comment. Removing it would need a lock around every offer, which is a cost on the hot path to fix a shutdown-only corner.

Register shutdown() as a JVM shutdown hook (Runtime.getRuntime().addShutdownHook), an atexit handler in Python, or a beforeExit handler in Node. Otherwise a daemon writer thread dies with the process and the last few lines are lost, which are often the most useful lines in the file.

8. Extensions: "the interviewer adds X"

Extension A: "Set DEBUG for app.db and everything under it, but leave app.web at INFO"

This is hierarchical loggers, the feature every real library has. Logger names are dotted paths, and the effective level is the level of the nearest configured ancestor: app.db.pool → app.db → app → root. Because LogManager.levelFor was left overridable, it's a subclass with a map of prefixes.

# file: ext_hierarchy.py
"""Hierarchical levels: the nearest configured ancestor wins."""
from typing import Dict

from logkit import Level, LogManager, MemoryAppender, AppenderHandler, MessageOnly


class HierarchicalLogManager(LogManager):
    def __init__(self, *args, **kwargs) -> None:
        super().__init__(*args, **kwargs)
        self._levels: Dict[str, Level] = {}

    def set_level(self, prefix: str, level: Level) -> None:
        self._levels[prefix] = level

    def level_for(self, logger_name: str) -> Level:
        name = logger_name
        while name:
            if name in self._levels:
                return self._levels[name]
            name = name.rpartition(".")[0]  # "app.db.pool" -> "app.db" -> "app" -> ""
        return self.root_level


if __name__ == "__main__":
    lm = HierarchicalLogManager()
    memory = MemoryAppender()
    lm.configure(Level.INFO, AppenderHandler(Level.TRACE, MessageOnly(), memory))
    lm.set_level("app.db", Level.DEBUG)
    lm.set_level("app.db.noisy", Level.ERROR)

    lm.get_logger("app.db.pool").debug("pool debug")      # inherits DEBUG from app.db
    lm.get_logger("app.db.noisy.x").warn("noisy warn")    # ERROR from app.db.noisy wins
    lm.get_logger("app.web").debug("web debug")           # root INFO, dropped
    lm.get_logger("app.dbx").debug("not a child")         # "app.dbx" is not under "app.db"
    assert memory.lines() == ["pool debug"], memory.lines()
    print("ext_hierarchy.py ok:", memory.lines())

Two details matter. The walk splits on dots, so app.dbx isn't treated as a child of app.db. That's a classic bug with startswith. And the walk is O(depth) per call. If profiling shows it, cache the effective level per logger and invalidate the cache whenever set_level runs. Log4j and Logback both precompute effective levels for this reason.

Extension B: "One bad deploy logged the same error 50,000 times a second and filled the disk"

Add a rate-limiting filter to the front of the chain. It allows at most N identical messages per window and silently counts the rest. This is Chain of Responsibility in its original, stopping form: returning false ends the chain for that record. The window uses the injected clock, so tests don't sleep.

// file: RateLimitFilterDemo.java
import java.time.*;
import java.util.*;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.atomic.AtomicLong;

/** Lets at most `limit` records per (logger, message) through each window. */
final class RateLimitFilter extends Handler {
    private record Window(long startMillis, int count) {}

    private final int limit;
    private final long windowMillis;
    private final Clock clock;
    private final ConcurrentHashMap<String, Window> windows = new ConcurrentHashMap<>();
    private final AtomicLong suppressed = new AtomicLong();

    RateLimitFilter(int limit, Duration window, Clock clock) {
        this.limit = limit;
        this.windowMillis = window.toMillis();
        this.clock = clock;
    }

    protected boolean process(LogRecord r) {
        long now = clock.millis();
        String key = r.logger() + "|" + r.message();
        // compute() runs atomically per key, so two threads can't both take the last slot.
        Window w = windows.compute(key, (k, old) ->
            old == null || now - old.startMillis() >= windowMillis ? new Window(now, 1)
                                                                   : new Window(old.startMillis(), old.count() + 1));
        if (w.count() <= limit) return true;
        suppressed.incrementAndGet();
        return false; // stop the chain: nothing downstream sees this record
    }

    long suppressed() { return suppressed.get(); }
}

/** A clock tests can move. */
final class MutableClock extends Clock {
    private Instant now;
    MutableClock(Instant start) { now = start; }
    void advance(Duration d) { now = now.plus(d); }
    public Instant instant() { return now; }
    public ZoneId getZone() { return ZoneOffset.UTC; }
    public Clock withZone(ZoneId zone) { return this; }
}

class RateLimitFilterDemo {
    public static void main(String[] args) {
        MutableClock clock = new MutableClock(Instant.parse("2026-11-10T00:00:00Z"));
        LogManager lm = new LogManager(clock);
        MemoryAppender memory = new MemoryAppender();
        RateLimitFilter limiter = new RateLimitFilter(3, Duration.ofSeconds(1), clock);
        limiter.linkWith(new AppenderHandler(Level.TRACE, LogRecord::message, memory));
        lm.configure(Level.INFO, limiter);
        Logger log = lm.getLogger("orders");

        for (int i = 0; i < 1000; i++) log.error("db connection refused");
        log.error("a different error"); // separate key, its own budget
        clock.advance(Duration.ofSeconds(1));
        log.error("db connection refused"); // new window

        long refused = memory.lines().stream().filter(l -> l.equals("db connection refused")).count();
        if (refused != 4) throw new AssertionError("expected 3 + 1, got " + refused);
        if (!memory.lines().contains("a different error")) throw new AssertionError("other keys unaffected");
        if (limiter.suppressed() != 997) throw new AssertionError("suppressed " + limiter.suppressed());
        System.out.println("RateLimitFilterDemo ok, suppressed=" + limiter.suppressed());
    }
}

In production you'd also emit a summary line when a window closes ("suppressed 997 similar messages"), so the volume isn't invisible. The windows map needs a bound too: key it on a message template rather than the formatted text, or the map grows with every unique order ID. This is the same fixed-window algorithm as the Rate Limiter case study, applied to logs.

Extension C: "Ship logs as JSON to our log pipeline, and never log a card number"

Two independent changes. JSON is a new Formatter. Redaction is a Decorator around any formatter: it rewrites the record's message and context, then delegates. Because redaction runs on the record and not on the output string, it can't be defeated by a formatter that escapes characters differently.

// file: ext-json.ts
import { AppenderHandler, Formatter, Level, LogManager, LogRecord, MemoryAppender, withContext } from "./logkit";

export class JsonFormatter implements Formatter {
  format(r: LogRecord): string {
    return JSON.stringify({
      ts: r.time.toISOString(), level: Level[r.level], logger: r.logger, msg: r.message,
      ...r.context, ...(r.error ? { error: r.error.message } : {}),
    });
  }
}

/** Decorator: scrubs secrets from the record, then lets the inner formatter do its job. */
export class RedactingFormatter implements Formatter {
  private static readonly CARD = /\b(?:\d[ -]?){12,15}(\d{4})\b/g;
  constructor(private readonly inner: Formatter, private readonly secretKeys: ReadonlySet<string>) {}

  format(r: LogRecord): string {
    const context: Record<string, string> = {};
    for (const [k, v] of Object.entries(r.context)) context[k] = this.secretKeys.has(k) ? "***" : this.scrub(v);
    return this.inner.format({ ...r, message: this.scrub(r.message), context });
  }

  private scrub(s: string): string { return s.replace(RedactingFormatter.CARD, "****$1"); }
}

const lm = new LogManager(() => new Date("2026-11-10T09:30:00Z"));
const memory = new MemoryAppender();
lm.configure(Level.INFO, new AppenderHandler(Level.TRACE,
  new RedactingFormatter(new JsonFormatter(), new Set(["authToken"])), memory));

withContext({ requestId: "r-7", authToken: "eyJhbGciOi..." }, () =>
  lm.getLogger("pay").info("charging card 4111 1111 1111 1234 for 20.00"));

const parsed = JSON.parse(memory.lines[0]);
if (parsed.msg !== "charging card ****1234 for 20.00") throw new Error(`card leaked: ${parsed.msg}`);
if (parsed.authToken !== "***" || parsed.requestId !== "r-7") throw new Error("context redaction");
if (parsed.level !== "INFO" || parsed.ts !== "2026-11-10T09:30:00.000Z") throw new Error("json shape");
console.log("ext-json.ts ok:", memory.lines[0]);

Regex redaction is a safety net, not a guarantee. The real fix is to never put secrets into log calls, which you enforce in code review and with types (a Secret wrapper whose toString() returns ***).

9. Testing

A logging framework is unusually easy to test once outputs and time are injectable, which is one more argument for not making LogManager a hard singleton. Every test builds its own manager with a fixed clock and a MemoryAppender, and asserts on exact strings.

What to cover:

  1. Level filtering at both layers. Logger level and handler threshold.
  2. Laziness. A disabled supplier is never invoked. Count invocations.
  3. Chain behaviour. A filter that returns false stops downstream handlers. A failing handler doesn't stop the next one and doesn't throw to the caller.
  4. Formatting. Exact line for a fixed clock. Context in sorted key order so the output is deterministic.
  5. MDC. Present inside a scope, restored after it (including after an exception), isolated between threads.
  6. Rotation. File sizes stay at or below the limit, the backup count is respected, and the newest line is in the base file.
  7. Async delivery. Many threads, BLOCK policy: nothing lost, per-thread order kept. DROP policy: errors kept, drops counted, written + dropped == sent.
  8. Shutdown drains. Everything accepted before close() is written.
// file: LoggingTests.java
import java.time.*;
import java.util.*;
import java.util.concurrent.*;

class LoggingTests {
    static int passed;

    static void test(String name, Runnable body) {
        body.run();
        passed++;
        System.out.println("  ok  " + name);
    }

    static void check(boolean ok, String msg) { if (!ok) throw new AssertionError(msg); }

    static LogManager manager(MemoryAppender memory, Handler... extraFront) {
        LogManager lm = new LogManager(Clock.fixed(Instant.EPOCH, ZoneOffset.UTC));
        Handler sink = new AppenderHandler(Level.TRACE, LogRecord::message, memory);
        if (extraFront.length == 0) { lm.configure(Level.INFO, sink); return lm; }
        extraFront[0].linkWith(sink);
        lm.configure(Level.INFO, extraFront[0]);
        return lm;
    }

    public static void main(String[] args) throws Exception {
        test("a failing handler does not stop the chain or throw", () -> {
            MemoryAppender memory = new MemoryAppender();
            Handler broken = new FilterHandler(r -> { throw new IllegalStateException("boom"); });
            LogManager lm = manager(memory, broken);
            lm.getLogger("x").info("still delivered");
            check(memory.lines().equals(List.of("still delivered")), memory.lines().toString());
        });
        test("handler threshold is applied after logger level", () -> {
            MemoryAppender memory = new MemoryAppender();
            LogManager lm = new LogManager(Clock.systemUTC());
            lm.configure(Level.DEBUG, new AppenderHandler(Level.WARN, LogRecord::message, memory));
            Logger log = lm.getLogger("x");
            log.debug("d"); log.info("i"); log.warn("w"); log.error("e");
            check(memory.lines().equals(List.of("w", "e")), memory.lines().toString());
        });
        test("mdc is restored after an exception", () -> {
            try (Mdc.Scope s = Mdc.scoped("user", "u1")) { throw new RuntimeException("x"); }
            catch (RuntimeException expected) { }
            check(Mdc.snapshot().isEmpty(), "context leaked");
        });
        test("mdc is isolated between threads", () -> {
            Mdc.put("user", "main-user");
            try {
                String seen = CompletableFuture.supplyAsync(() -> Mdc.snapshot().get("user")).join();
                check(seen == null, "pool thread saw main's context");
            } finally { Mdc.clear(); }
        });
        test("shutdown drains every accepted record", () -> {
            MemoryAppender memory = new MemoryAppender();
            LogManager lm = new LogManager(Clock.systemUTC());
            lm.configure(Level.INFO, new AsyncHandler(new AppenderHandler(Level.TRACE, LogRecord::message, memory),
                4, AsyncHandler.Overflow.BLOCK, Level.WARN));
            for (int i = 0; i < 500; i++) lm.getLogger("x").info("m" + i);
            lm.shutdown();
            check(memory.lines().size() == 500, "lost " + (500 - memory.lines().size()));
        });
        System.out.println("LoggingTests: " + passed + " passed");
    }
}
# file: test_logkit.py
import threading
import unittest

from logkit import (AppenderHandler, AsyncHandler, FilterHandler, Level, LogManager,
                    MemoryAppender, MessageOnly, mdc, _mdc)


def make(memory, front=None):
    lm = LogManager()
    sink = AppenderHandler(Level.TRACE, MessageOnly(), memory)
    if front is not None:
        front.link_with(sink)
    lm.configure(Level.INFO, front or sink)
    return lm


class LoggingTest(unittest.TestCase):
    def test_filter_stops_the_chain(self):
        memory = MemoryAppender()
        lm = make(memory, FilterHandler(lambda r: not r.message.startswith("skip")))
        lm.get_logger("x").info("skip me")
        lm.get_logger("x").info("keep me")
        self.assertEqual(memory.lines(), ["keep me"])

    def test_failing_handler_does_not_raise(self):
        memory = MemoryAppender()

        def boom(_):
            raise RuntimeError("boom")

        lm = make(memory, FilterHandler(boom))
        lm.get_logger("x").info("still delivered")
        self.assertEqual(memory.lines(), ["still delivered"])

    def test_mdc_restored_after_exception(self):
        with self.assertRaises(ValueError):
            with mdc(user="u1"):
                raise ValueError()
        self.assertEqual(dict(_mdc.get()), {})

    def test_new_thread_starts_with_empty_context(self):
        seen = {}
        with mdc(user="main"):
            t = threading.Thread(target=lambda: seen.update(_mdc.get()))
            t.start()
            t.join()
        self.assertEqual(seen, {})

    def test_shutdown_drains(self):
        memory = MemoryAppender()
        lm = LogManager()
        lm.configure(Level.INFO, AsyncHandler(AppenderHandler(Level.TRACE, MessageOnly(), memory), 4))
        for i in range(500):
            lm.get_logger("x").info(f"m{i}")
        lm.shutdown()
        self.assertEqual(len(memory.lines()), 500)


if __name__ == "__main__":
    unittest.main(verbosity=2)
// file: logkit.test.ts
import { test } from "node:test";
import assert from "node:assert/strict";
import { AppenderHandler, AsyncHandler, FilterHandler, Handler, Level, LogManager, MemoryAppender, withContext } from "./logkit";

function make(memory: MemoryAppender, front?: Handler): LogManager {
  const lm = new LogManager();
  const sink = new AppenderHandler(Level.TRACE, { format: (r) => r.message }, memory);
  if (front) front.linkWith(sink);
  lm.configure(Level.INFO, front ?? sink);
  return lm;
}

test("filter stops the chain", () => {
  const memory = new MemoryAppender();
  const lm = make(memory, new FilterHandler((r) => !r.message.startsWith("skip")));
  lm.getLogger("x").info("skip me");
  lm.getLogger("x").info("keep me");
  assert.deepEqual(memory.lines, ["keep me"]);
});

test("a throwing handler does not reach the caller", () => {
  const memory = new MemoryAppender();
  const lm = make(memory, new FilterHandler(() => { throw new Error("boom"); }));
  assert.doesNotThrow(() => lm.getLogger("x").info("still delivered"));
  assert.deepEqual(memory.lines, ["still delivered"]);
});

test("context does not leak across concurrent async flows", async () => {
  const memory = new MemoryAppender();
  const lm = new LogManager();
  lm.configure(Level.INFO, new AppenderHandler(Level.TRACE, { format: (r) => `${r.context.id}=${r.message}` }, memory));
  const log = lm.getLogger("x");
  await Promise.all(["a", "b", "c"].map((id) => withContext({ id }, async () => {
    await new Promise((r) => setTimeout(r, 1));
    log.info(id);
  })));
  assert.ok(memory.lines.every((l) => { const [ctx, msg] = l.split("="); return ctx === msg; }));
});

test("shutdown flushes the async queue", async () => {
  const memory = new MemoryAppender();
  const lm = new LogManager();
  lm.configure(Level.INFO, new AsyncHandler(new AppenderHandler(Level.TRACE, { format: (r) => r.message }, memory), 1000));
  for (let i = 0; i < 500; i++) lm.getLogger("x").info(`m${i}`);
  assert.equal(memory.lines.length, 0, "nothing written synchronously");
  await lm.shutdown();
  assert.equal(memory.lines.length, 500);
});

10. Common mistakes

  1. Formatting before the level check. log.debug("user=" + user.toJson()) serializes the user even when DEBUG is off. Check first, or accept a supplier.
  2. One giant Logger class. Levels, formatting, file handling and rotation in one class means every change touches everything. The interviewer is looking for the formatter/appender split.
  3. An unbounded async queue. It hides back-pressure until the heap fills. The failure moves from "logs are slow" to "the service is down".
  4. Dropping errors under load. A drop policy that treats ERROR like DEBUG throws away exactly the line you'll need in the post-mortem.
  5. Holding a live reference to the MDC in the record. Async formatting then prints a different request's context. Snapshot at log time.
  6. Never clearing MDC on pooled threads. The next request inherits the previous user's ID. Use scoped helpers.
  7. Letting appender exceptions escape. A full disk becomes a failed checkout. Catch inside the chain, report to stderr, carry on.
  8. No shutdown flush. The daemon worker dies with the JVM and the crash's last lines are lost. Register a shutdown hook.
  9. A hard Singleton with a private constructor. It works until the first test that needs two configurations, or parallel tests that both assert on output.
  10. Double-checked locking written wrong. If you do lazy init by hand in Java, the field must be volatile. Better to use a static final field or the holder idiom and let the JVM do it.
  11. A SimpleDateFormat shared across threads. It's mutable and not thread-safe, so timestamps come out garbled. Use DateTimeFormatter.
  12. Rotation without a lock. Two threads both rotate and one file disappears.
  13. Over-engineering the level type. A Level class hierarchy with DebugLevel extends Level adds nothing over an ordered enum.

11. Interview follow-ups

"Why Chain of Responsibility and not Observer?" Observer broadcasts the same event to every subscriber with no ordering and no way for one to stop the others. Logging needs ordering (filters before writers), the ability to stop a record (filters, rate limits), and wrapping (an async handler that owns a downstream chain). A chain gives all three. If the requirement were only "fan out to N destinations", Observer, or a plain list, would be simpler.

"How do Log4j 2, Logback and Python logging map onto this design?" Log4j 2: Logger → LoggerConfig with Filters → Appenders, each with a Layout. ThreadContext is the MDC. Its async loggers use the LMAX Disruptor ring buffer instead of a blocking queue to cut contention. Logback: Logger → appenders with Encoder/Layout, MDC, AsyncAppender with discardingThreshold and neverBlock, RollingFileAppender with size and time policies. Python: Logger → Handlers (each with a level, Filters and a Formatter), propagation to parent loggers, QueueHandler plus QueueListener for async, RotatingFileHandler and TimedRotatingFileHandler. SLF4J is a facade: application code depends on its interface, and the binding picks the implementation. That's the Dependency Inversion Principle applied to logging.

"Should Logger be an interface?" Yes, if callers should depend on an API rather than an implementation, which is exactly why SLF4J exists. Inside this small framework it's a concrete class because there's one implementation. If asked to support swapping the backend, extract the interface and make LogManager the factory.

"Where should the timestamp come from: when log() is called, or when the worker writes?" When log() is called. The record is a snapshot of the event. If the worker stamped it, a backed-up queue would make every line look later than it happened, and ordering across services would become meaningless.

"What's the cost of async logging?" Latency to durability: a line accepted into the queue isn't on disk yet, so a hard crash can lose up to a queue's worth. A thread and a queue's memory. And a policy decision about overflow. For audit logs where every line must survive, use synchronous writes, or async with BLOCK and an explicit fsync policy. For high-volume debug logs, async with drop is right.

"How would you test that logging is cheap when disabled?" Behaviourally, by asserting a supplier isn't called. For actual cost, a microbenchmark harness (JMH in Java) comparing a disabled call to an empty method. Don't trust a hand-timed loop, because the JIT will eliminate dead code.

"How do you change log levels in production without a restart?" Levels are volatile, so a setter is already safe to call at runtime. Expose it through an admin endpoint or watch a config file. Log4j and Logback both support periodic config reload. If you cached effective levels (Extension A), invalidate the cache on change.

"Is a static getLogger inside every class a Singleton smell?" It's a service-locator call, and its usual downside (hidden dependencies) matters much less when the dependency doesn't affect behaviour. The practical test: can a test capture and assert on log output without global state? With an injectable LogManager, yes. That's the line between a convenient global and a harmful Singleton.

"How would this change for a distributed system?" Locally the design stays the same. The appender becomes "write JSON lines to stdout or a local file", and an agent (Fluent Bit, Vector, the OpenTelemetry Collector) ships them. The MDC gains a trace ID propagated through request headers, so lines from different services can be joined. Central storage and search are a high-level design problem.