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
| Question | Why it matters | Answer we'll assume |
|---|---|---|
| Which levels? Can they be set per logger? | Drives the Level type and level inheritance | TRACE, DEBUG, INFO, WARN, ERROR. Per-logger override, otherwise a root level |
| Where does output go? | Number and kind of appenders | Console, 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 pipeline | Yes: e.g. everything to console, WARN+ to a file |
| What format? Text, JSON? | Formatter as a pluggable piece | Text pattern now, JSON as an extension |
| Synchronous or asynchronous? | Whether the caller's thread pays for I/O | Both. Async must be bounded |
| If the async queue fills up, block or drop? | Back-pressure policy | Configurable. Never drop WARN and above |
| Do we need per-request context (request ID, user ID)? | MDC, and how it crosses threads | Yes |
| Multiple threads? | Interleaved lines, appender safety | Yes |
| Must logging ever crash the app? | Error handling inside appenders | Never. Failures go to stderr |
| Configuration from a file? | A config parser, hot reload | Out of scope. Configure in code |
Functional requirements
logger.info("...")and friends at five levels, pluserror(message, throwable).- A record below the effective level is discarded before any formatting work.
- Expensive messages can be passed as a lambda and are only evaluated if enabled.
- Records pass through a configurable chain of handlers. A handler may write, filter, or forward.
- Appenders: console, plain file, size-based rotating file with N backups, in-memory.
- Formatters turn a record into a line. Timestamp, level, thread, logger name, message, context, stack trace.
- Context (MDC): key/value pairs set once per request and included automatically on every record.
- An async handler decouples callers from slow appenders, with a bounded queue and a choice of block or drop.
shutdown()flushes everything that was accepted.
Non-functional requirements
- Cheap when disabled. A disabled
debugcall 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
| Entity | Responsibility |
|---|---|
Level | Ordered severity. atLeast(other) is the only operation that matters |
LogRecord | Immutable snapshot of one event: time, level, logger name, thread, message, context, error |
Logger | The API callers use. Checks the level, builds the record, hands it to the manager |
LogManager | Registry of named loggers, owns the root level and the handler chain, and the clock |
Handler | One link in the chain. Processes a record, then decides whether to pass it on |
AppenderHandler | A handler that formats and writes if the record meets its own threshold |
FilterHandler | A handler that can stop the chain (drop noise) |
AsyncHandler | A handler that queues records for a background worker that runs a downstream chain |
Formatter | Record → string. Stateless |
Appender | String → destination. Owns the I/O resource |
Mdc | Per-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
AsyncAppenderdoes almost exactly this. ItsdiscardingThresholddrops TRACE/DEBUG/INFO once the queue is 80% full, andneverBlockswitches 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
| State | Who touches it | Protection |
|---|---|---|
| Logger registry | Any thread calling getLogger | ConcurrentHashMap.computeIfAbsent (Java), a lock (Python) |
| Root level, chain head | Read on every call, written at configure time | volatile reads, no lock on the hot path |
| A logger's own level | Read on every call | volatile |
| Appender state: file handle, byte count | Every writing thread, or the one async worker | synchronized / a lock per appender |
| The async queue | All producers, one consumer | ArrayBlockingQueue / queue.Queue are thread-safe |
| Drop counter | Producers | AtomicLong / a small lock |
| MDC | Only the owning thread | ThreadLocal / 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:
- Always clear or restore.
Mdc.scopedin a try-with-resources (Java) orwith mdc(...)(Python) guarantees restoration even when exceptions fly. Pool threads are reused, so a forgottenputleaks into the next request. - 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'sMDC.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:
- Level filtering at both layers. Logger level and handler threshold.
- Laziness. A disabled supplier is never invoked. Count invocations.
- Chain behaviour. A filter that returns
falsestops downstream handlers. A failing handler doesn't stop the next one and doesn't throw to the caller. - Formatting. Exact line for a fixed clock. Context in sorted key order so the output is deterministic.
- MDC. Present inside a scope, restored after it (including after an exception), isolated between threads.
- Rotation. File sizes stay at or below the limit, the backup count is respected, and the newest line is in the base file.
- Async delivery. Many threads, BLOCK policy: nothing lost, per-thread order kept. DROP policy: errors kept, drops counted,
written + dropped == sent. - 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
- Formatting before the level check.
log.debug("user=" + user.toJson())serializes the user even when DEBUG is off. Check first, or accept a supplier. - One giant
Loggerclass. Levels, formatting, file handling and rotation in one class means every change touches everything. The interviewer is looking for the formatter/appender split. - An unbounded async queue. It hides back-pressure until the heap fills. The failure moves from "logs are slow" to "the service is down".
- Dropping errors under load. A drop policy that treats ERROR like DEBUG throws away exactly the line you'll need in the post-mortem.
- Holding a live reference to the MDC in the record. Async formatting then prints a different request's context. Snapshot at log time.
- Never clearing MDC on pooled threads. The next request inherits the previous user's ID. Use scoped helpers.
- Letting appender exceptions escape. A full disk becomes a failed checkout. Catch inside the chain, report to stderr, carry on.
- No shutdown flush. The daemon worker dies with the JVM and the crash's last lines are lost. Register a shutdown hook.
- 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.
- Double-checked locking written wrong. If you do lazy init by hand in Java, the field must be
volatile. Better to use astatic finalfield or the holder idiom and let the JVM do it. - A
SimpleDateFormatshared across threads. It's mutable and not thread-safe, so timestamps come out garbled. UseDateTimeFormatter. - Rotation without a lock. Two threads both rotate and one file disappears.
- Over-engineering the level type. A
Levelclass hierarchy withDebugLevel extends Leveladds 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.
Related
- Chain of Responsibility, Strategy, Decorator, Singleton: the patterns used on this page.
- Concurrency Patterns in LLD: producer–consumer and bounded queues in depth.
- Designing for Testability: injected clocks and in-memory sinks.
- Design a Notification Service: another fan-out to channels with retries and back-pressure.