SyntaxPilot
Courses/Low-Level Design/Lesson 67
Video coming soonThis lesson’s video is being made

Start with the notes below; the video appears here as soon as it is on YouTube.

Low-Level Design · Lesson 67 of 90

Design a logging framework

logging frameworkLoggerlog levels DEBUG INFO WARN ERRORLogMessageAppenderconsole and file appendersFormatterChain of Responsibility by levelSingleton loggerconfigurationasynchronous logging with a queue

These are the notes for Low-Level Design (LLD) episode 67: designing a logging framework, a common machine-coding question and a piece of code every real application runs all day. We start from System.out.println everywhere, watch it fail, and fix each failure with one idea: log levels and a threshold, a LogMessage, Appenders (console and file) and Formatters, a Singleton log manager with configuration, the Chain of Responsibility to give each destination its own level, and asynchronous logging with a queue.

How the code was run: every program was saved as Main.java in a fresh folder and run with javac Main.java && java -cp . Main on OpenJDK 21. Every output below is the real output, pasted exactly (times and millisecond counts change from run to run). The orders, the bank and the "5 ms disk" are made up for teaching.

1. The problem: the society gate register

At the society gate In software
The guard writes every event in a register: time, who, which flat, why A log: a record of what the program did, written while it runs
A courier is routine; a stranger trying three flats is a warning; a fire is an emergency Log levels: DEBUG, INFO, WARN, ERROR
Routine entries go only in the register; an emergency also means phoning the secretary Appenders: different destinations (console, file, pager)
One register and one set of rules for every guard and shift One log manager with one configuration

2. What logging is

  • Log: a record of what a program did, written while it runs. Example: 16:25:14 ERROR [main] payment FAILED for order 742.
  • Log message (log record, log event): one entry: when (a timestamp), how serious (a level), where (the thread, the class), and what (the text).
  • Production: the live system real users use. There is no debugger there, so when a payment fails at 3 a.m., the log is all you get.
  • Logging framework: reusable code that gives every class a logger and decides what is written, how it looks and where it goes.

3. Attempt 1: System.out.println everywhere

To count the lines, out stands in for System.out.println: it keeps every printed line in a list called console.

import java.util.*;
public class Main {
    static List<String> console = new ArrayList<>();   // every println, kept so we can count them
    static void out(String s) { console.add(s); }       // stands in for System.out.println(s)
    static void pay(int order) {
        out("checking cart for order " + order);
        out("calling bank for order " + order);
        if (order == 742) out("payment FAILED for order " + order);   // the one line that matters
        out("done order " + order);
    }
    public static void main(String[] args) {
        for (int order = 1; order <= 1000; order++) pay(order);
        int at = console.indexOf("payment FAILED for order 742");
        System.out.println("lines printed: " + console.size());
        System.out.println("the failure is line " + (at + 1) + ", between:");
        for (int i = at - 2; i <= at + 2; i++) System.out.println("  " + console.get(i));
    }
}

Real output:

lines printed: 3001
the failure is line 2226, between:
  checking cart for order 742
  calling bank for order 742
  payment FAILED for order 742
  done order 742
  checking cart for order 743

The one line that matters, payment FAILED for order 742, is line 2,226 of 3,001, between routine lines that look just like it.

Why it failed

  • Every line looks equally important: no level.
  • No time, no thread, no class name.
  • It only goes to the console.
  • The only way to make it quieter is to delete code.

4. Log levels and a threshold

A log level says how serious a message is. Levels are ordered:

Level Meaning Example
DEBUG Details for developers while finding a bug checking cart for order 742
INFO Normal, expected events order 742 placed
WARN Something odd, not broken yet bank slow for order 400
ERROR Something failed payment FAILED for order 742

The threshold is the lowest level that gets through. Threshold WARN → DEBUG and INFO are dropped; WARN and ERROR are written.

Java tools used: - enum: a type with a fixed, ordered list of values. Level.WARN.compareTo(Level.INFO) is positive because WARN comes later in the list. - record: a short class that only holds data: record LogMessage(Level level, String thread, String text) {} gives a constructor, getters (m.level()), equals, hashCode and toString.

enum Level { DEBUG, INFO, WARN, ERROR }               // least serious ... most serious
record LogMessage(Level level, String thread, String text) {}
class Logger {
    private Level threshold;                          // the lowest level that gets through
    Logger(Level threshold) { this.threshold = threshold; }
    void setLevel(Level level) { threshold = level; }
    void log(Level level, String text) {
        if (level.compareTo(threshold) < 0) return;   // below the threshold: dropped, costs almost nothing
        LogMessage m = new LogMessage(level, Thread.currentThread().getName(), text);
        System.out.println(m.level() + " [" + m.thread() + "] " + m.text());
    }
    void debug(String t) { log(Level.DEBUG, t); }   void info(String t)  { log(Level.INFO, t); }
    void warn(String t)  { log(Level.WARN, t); }    void error(String t) { log(Level.ERROR, t); }
}
public class Main {
    static Logger log = new Logger(Level.WARN);
    static void pay(int order) {
        log.debug("checking cart for order " + order);
        if (order % 400 == 0) log.warn("bank slow for order " + order);
        if (order == 742) log.error("payment FAILED for order " + order);
        log.debug("done order " + order);
    }
    public static void main(String[] args) {
        for (int order = 1; order <= 1000; order++) pay(order);
        log.setLevel(Level.DEBUG);                    // one switch: DEBUG is back, no code deleted
        pay(1001);
    }
}

Real output:

WARN [main] bank slow for order 400
ERROR [main] payment FAILED for order 742
WARN [main] bank slow for order 800
DEBUG [main] checking cart for order 1001
DEBUG [main] done order 1001

Five lines instead of 3,001, and one call to setLevel(Level.DEBUG) brings the detail back without deleting code. A dropped message costs almost nothing: one comparison and a return.

5. Appenders and Formatters

Next we want the console while developing, a file on the server, and errors on a pager. The obvious way grows a pile of flags and ifs inside Logger:

class Logger {
  boolean toConsole, toFile, toPager, asJson;
  void log(Level level, String text) {
    String line = asJson ? toJson(level, text) : level + " " + text;
    if (toConsole) System.out.println(line);
    if (toFile)    writeToFile(line);
    if (toPager && level == Level.ERROR) page(line);
    // Slack? email? XML? edit THIS class again
  }
}

Every new destination or format means editing Logger again: it breaks the Open-Closed Principle (episode 13). The fix splits the job into three building blocks:

Block Answers Example
LogMessage WHAT happened record LogMessage(LocalTime time, Level level, String thread, String text)
Formatter HOW a line looks plain 16:25:14 INFO [main] order 742 placed, or JSON {"level":"INFO","msg":"order 742 placed"}
Appender WHERE it goes ConsoleAppender (prints), FileAppender (adds to a file), a network appender
  • JSON (JavaScript Object Notation): text with names and values in curly braces, easy for machines to read; log search tools love it.
  • Lambda: a short function written inline, e.g. m -> m.level() + " " + m.text(). Because Formatter has one method, a lambda can be a Formatter.
  • Rule: a failing appender must never crash the application. FileAppender catches the exception and prints a warning instead.
import java.nio.file.*;  import java.time.LocalTime;  import java.util.*;
import static java.nio.file.StandardOpenOption.*;
enum Level { DEBUG, INFO, WARN, ERROR }
record LogMessage(LocalTime time, Level level, String thread, String text) {}
interface Formatter { String format(LogMessage m); }                 // HOW a line looks
interface Appender { void append(LogMessage m); }                    // WHERE a line goes
class ConsoleAppender implements Appender { final Formatter f;  ConsoleAppender(Formatter f) { this.f = f; }
    public void append(LogMessage m) { System.out.println(f.format(m)); } }
class FileAppender implements Appender {  private final Path file;  private final Formatter f;
    FileAppender(String name, Formatter f) { file = Path.of(name);  this.f = f; }
    public void append(LogMessage m) {
        try { Files.writeString(file, f.format(m) + "\n", CREATE, APPEND); }
        catch (Exception e) { System.err.println("log write failed: " + e); } } }   // never crash the app
class Logger {
    private final Level threshold;  private final List<Appender> appenders = new ArrayList<>();
    Logger(Level threshold) { this.threshold = threshold; }
    Logger add(Appender a) { appenders.add(a);  return this; }
    void log(Level level, String text) {  if (level.compareTo(threshold) < 0) return;
        LogMessage m = new LogMessage(LocalTime.now(), level, Thread.currentThread().getName(), text);
        for (Appender a : appenders) a.append(m); } }                // the Logger never knows WHERE
public class Main { public static void main(String[] args) throws Exception {
    Formatter plain = m -> m.time().withNano(0) + " " + m.level() + " [" + m.thread() + "] " + m.text();
    Formatter json  = m -> String.format("{\"level\":\"%s\",\"msg\":\"%s\"}", m.level(), m.text());
    Files.deleteIfExists(Path.of("app.log"));
    Logger log = new Logger(Level.INFO).add(new ConsoleAppender(plain)).add(new FileAppender("app.log", json));
    log.log(Level.DEBUG, "cart has 3 items");  log.log(Level.INFO, "order 742 placed");
    log.log(Level.ERROR, "payment FAILED for order 742");
    System.out.println("--- app.log ---");
    Files.readAllLines(Path.of("app.log")).forEach(System.out::println); } }

Real output:

16:25:14 INFO [main] order 742 placed
16:25:14 ERROR [main] payment FAILED for order 742
--- app.log ---
{"level":"INFO","msg":"order 742 placed"}
{"level":"ERROR","msg":"payment FAILED for order 742"}

The DEBUG line is dropped (threshold INFO). The same message goes to two places in two formats, and Logger never changed.

6. Who creates the Logger? Attempt: new Logger() in every class

enum Level { DEBUG, INFO, WARN, ERROR }
class Logger {                                        // attempt: every class makes its own Logger
    static int created = 0;
    private final String name;  private Level threshold = Level.INFO;
    Logger(String name) { this.name = name;  created++; }
    void setLevel(Level level) { threshold = level; }
    void log(Level level, String text) {
        if (level.compareTo(threshold) >= 0) System.out.println(level + " " + name + ": " + text); }
}
class OrderService {   static final Logger log = new Logger("OrderService");
    void place() { log.log(Level.DEBUG, "order 742 placed"); } }
class PaymentService { static final Logger log = new Logger("PaymentService");
    void pay()   { log.log(Level.DEBUG, "bank call took 950 ms"); } }
public class Main {
    public static void main(String[] args) {
        OrderService orders = new OrderService();  PaymentService payments = new PaymentService();
        OrderService.log.setLevel(Level.DEBUG);       // ops: "turn on DEBUG for the whole app!"
        orders.place();
        payments.pay();                               // the slow bank call: we need THIS line
        System.out.println("loggers created: " + Logger.created + ", each with its own level");
    }
}

Real output:

DEBUG OrderService: order 742 placed
loggers created: 2, each with its own level

Operations asked for DEBUG "for the whole app", but the setting lives in each logger. PaymentService's DEBUG line, the slow bank call we needed, is missing. With hundreds of classes, nobody can change hundreds of settings at 3 a.m.

7. Fix: a Singleton LogManager with configuration

  • Singleton (episode 22): a class with exactly one object. In Java the simplest safe way is an enum with one value, INSTANCE: the JVM creates it once, thread-safely, and it cannot be created with new (error: enum classes may not be instantiated).
  • Configuration: settings read from outside the code (a file, environment variables), so they change without recompiling. Java's Properties class reads key=value lines like level=DEBUG.
  • Loggers are still per class (a name like PaymentService), so every line says who wrote it, but each logger asks the manager for the level.
  • volatile on the level: when one thread changes it, every other thread sees the new value immediately.
  • computeIfAbsent(name, Logger::new): the same name always returns the same Logger object.
import java.util.*;
enum Level { DEBUG, INFO, WARN, ERROR }
enum LogManager {  INSTANCE;                          // enum singleton (episode 22): exactly one
    private volatile Level level = Level.INFO;
    private final Map<String, Logger> loggers = new HashMap<>();
    void configure(String text) throws Exception {   // configuration: settings from outside the code
        Properties p = new Properties();  p.load(new java.io.StringReader(text));
        level = Level.valueOf(p.getProperty("level", "INFO"));
        System.out.println("configured: level=" + level + ", appenders=" + p.getProperty("appenders")); }
    Level level() { return level; }
    synchronized Logger getLogger(String name) { return loggers.computeIfAbsent(name, Logger::new); }
    synchronized int count() { return loggers.size(); }
}
class Logger {
    private final String name;  Logger(String name) { this.name = name; }
    static Logger get(Class<?> c) { return LogManager.INSTANCE.getLogger(c.getSimpleName()); }
    void log(Level level, String text) {             // asks the ONE manager for the level, every time
        if (level.compareTo(LogManager.INSTANCE.level()) >= 0)
            System.out.println(level + " " + name + ": " + text); } }
class OrderService {   static final Logger log = Logger.get(OrderService.class);
    void place() { log.log(Level.DEBUG, "order 742 placed"); } }
class PaymentService { static final Logger log = Logger.get(PaymentService.class);
    void pay()   { log.log(Level.DEBUG, "bank call took 950 ms"); } }
public class Main { public static void main(String[] args) throws Exception {
    OrderService orders = new OrderService();  PaymentService payments = new PaymentService();
    LogManager.INSTANCE.configure("level=DEBUG\nappenders=console");   // ONE place, the whole app
    orders.place();  payments.pay();
    System.out.println("same object? " + (Logger.get(OrderService.class) == OrderService.log)
                       + ", loggers: " + LogManager.INSTANCE.count()); } }

Real output:

configured: level=DEBUG, appenders=console
DEBUG OrderService: order 742 placed
DEBUG PaymentService: bank call took 950 ms
same object? true, loggers: 2

One switch, the whole application.

8. Chain of Responsibility: a level per destination

With one threshold for the whole logger, every appender gets the same messages: set it to INFO and the pager rings for every order.

The Chain of Responsibility (episode 39) is a chain of handler objects, each holding a link to the next; a request is passed along the chain. Here every link checks "is this message serious enough for me?", writes it if so, and passes it on either way (a pass-through chain), so one message can be handled by several links.

Link Minimum level Real-life
ConsoleHandler DEBUG The guard's register: everything
FileHandler INFO The office file: the important ones
PagerHandler ERROR The secretary's phone: emergencies only
enum Level { DEBUG, INFO, WARN, ERROR }
record LogMessage(Level level, String text) {}
abstract class LogHandler {                                     // one link in the chain
    private final Level min;  private LogHandler next;  int count = 0;
    LogHandler(Level min) { this.min = min; }
    LogHandler then(LogHandler next) { this.next = next;  return next; }    // builds the chain
    final void handle(LogMessage m) {
        if (m.level().compareTo(min) >= 0) { count++;  write(m); }  // serious enough for me? write it
        if (next != null) next.handle(m); }                       // then pass it along the chain
    abstract void write(LogMessage m);
}
class ConsoleHandler extends LogHandler { ConsoleHandler(Level l) { super(l); }  void write(LogMessage m) {} }
class FileHandler extends LogHandler { FileHandler(Level l) { super(l); }  void write(LogMessage m) {} }
class PagerHandler extends LogHandler { PagerHandler(Level l) { super(l); }   // wakes the on-call engineer
    void write(LogMessage m) { if (count <= 2) System.out.println("  pager rings: " + m.text()); } }
public class Main {
    static void log(LogHandler first, Level l, String text) { first.handle(new LogMessage(l, text)); }
    static void day(String name, LogHandler console, LogHandler file, LogHandler pager) {
        console.then(file).then(pager);
        for (int order = 1; order <= 1000; order++) {
            log(console, Level.DEBUG, "cart checked " + order);  log(console, Level.INFO, "placed " + order);
            if (order % 400 == 0) log(console, Level.WARN, "bank slow " + order);
            if (order == 742) log(console, Level.ERROR, "payment FAILED " + order); }
        System.out.printf("%s: console %d, file %d, pager %d%n", name, console.count, file.count, pager.count);}
    public static void main(String[] args) {
        day("one level for all", new ConsoleHandler(Level.INFO), new FileHandler(Level.INFO),
                                 new PagerHandler(Level.INFO));
        day("a level per link ", new ConsoleHandler(Level.DEBUG), new FileHandler(Level.INFO),
                                 new PagerHandler(Level.ERROR)); } }

Real output:

  pager rings: placed 1
  pager rings: placed 2
one level for all: console 1003, file 1003, pager 1003
  pager rings: payment FAILED 742
a level per link : console 2003, file 1003, pager 1

One level for all: the pager rang 1003 times. A level per link: console 2003, file 1003, pager 1.

9. Asynchronous logging with a queue

Writing to a disk or the network takes time. A synchronous log call makes the request wait for every write. Asynchronous logging means log() only drops the line into a queue and returns; one background worker thread does the slow writing.

  • BlockingQueue: a thread-safe queue whose take() waits until an item arrives. ArrayBlockingQueue(10_000) is bounded: at most 10,000 lines wait, so a flood of logs can't use up all memory. offer() returns false when it's full (we drop and report; another policy is to wait with put()).
  • Daemon thread: a background thread Java does not wait for when the program ends. Lines still in the queue would be lost.
  • Poison pill: a special message (STOP) that tells the worker to finish. shutdown() puts the pill at the end of the queue and calls join(), which waits until the worker has written everything before it. (s != STOP compares object identity on purpose: only that exact object stops the worker.)
import java.util.concurrent.*;
class SlowAppender {                                  // pretend: a disk or network write, 5 ms each
    volatile int written = 0;
    void append(String line) { try { Thread.sleep(5); } catch (InterruptedException e) {}  written++; }
}
class AsyncLogger {
    private static final String STOP = "<stop>";      // a "poison pill": tells the worker to finish
    private final BlockingQueue<String> queue = new ArrayBlockingQueue<>(10_000);
    private final Thread worker;
    AsyncLogger(SlowAppender out) {
        worker = new Thread(() -> {                   // ONE background thread does the slow writing
            try { for (String s = queue.take(); s != STOP; s = queue.take()) out.append(s); }
            catch (InterruptedException e) {} });
        worker.setDaemon(true);  worker.start(); }
    void log(String line) { if (!queue.offer(line)) System.out.println("queue full, dropped"); }
    void shutdown() throws InterruptedException { queue.put(STOP);  worker.join(); }   // drain, then stop
}
public class Main { public static void main(String[] args) throws Exception {
    SlowAppender a = new SlowAppender();  long t = System.nanoTime();
    for (int i = 0; i < 200; i++) a.append("order " + i);             // synchronous: the request waits
    long ms = (System.nanoTime() - t) / 1_000_000;
    System.out.println("sync : request took " + ms + " ms, written " + a.written);
    SlowAppender b = new SlowAppender();  AsyncLogger log = new AsyncLogger(b);  t = System.nanoTime();
    for (int i = 0; i < 200; i++) log.log("order " + i);              // asynchronous: just a queue offer
    ms = (System.nanoTime() - t) / 1_000_000;  int done = b.written;
    System.out.println("async: request took " + ms + " ms, written " + done);
    System.out.println("if the app exits NOW, " + (200 - done) + " lines are lost");
    log.shutdown();
    System.out.println("after shutdown(): written " + b.written + " of 200"); } }

Real output:

sync : request took 1080 ms, written 200
async: request took 4 ms, written 0
if the app exits NOW, 200 lines are lost
after shutdown(): written 200 of 200

About a second synchronously; a few milliseconds asynchronously. Without shutdown() all 200 lines would be lost; with it, 200 of 200 are written.

10. The class diagram

LogManager  (enum Singleton: level + config, getLogger(name))
 └─creates──▶ Logger(name)   debug() info() warn() error()
                 └─builds──▶ LogMessage(time, level, thread, text)   a record
                 └─sends to─▶ queue ─▶ worker thread  (async, shutdown() drains)
LogHandler chain:  Console(DEBUG) ─▶ File(INFO) ─▶ Pager(ERROR)
                    each: level >= min? write it. Then pass it on.
Appender (where):  ConsoleAppender, FileAppender, ...
Formatter (how):   plain text, JSON, ...

Patterns used: Singleton (LogManager), Strategy (Formatter, Appender), Chain of Responsibility (level routing), Producer-consumer (async queue), Factory (Logger.get).

11. Real logging libraries

  • java.util.logging is built into the JDK. Its levels, printed by running the JDK 21 Level class (l.intValue()):
SEVERE 1000
WARNING 900
INFO 800
CONFIG 700
FINE 500
FINER 400
FINEST 300

and Logger.getLogger("orders") == Logger.getLogger("orders") printed true: the same name gives the same logger, just like our manager. - Apache Log4j 2 lists these standard levels: OFF, FATAL, ERROR, WARN, INFO, DEBUG, TRACE, ALL (Log4j 2 manual: custom log levels).

In a real project you use a library like these; in a machine-coding round you build the small version above to show the design.

12. Interview follow-ups

Follow-up Answer
Which lines belong to one request? Put a request id (correlation id) in every LogMessage, e.g. in a ThreadLocal set when the request starts
The log file grows forever Rotation: a new file every day or every N MB/lines; delete or archive old ones (mini project: every 2 lines)
Far too many DEBUG lines Sampling: keep 1 in N; or raise the level for noisy classes only
Passwords or card numbers in logs Mask secrets before formatting; never log them
Change the level without a restart Re-read the configuration file, or expose an admin endpoint that calls setLevel
The queue is full Drop with a counter (cheap, loses lines), or put() and block (safe, slows the app); report drops as a metric
Logging is slow even when disabled log.debug("x=" + expensive()) builds the string first; use if (isDebugEnabled()) or a Supplier<String>

13. Common mistakes

Mistake What you see (real) Why Fix
println everywhere lines printed: 3001, the failure is line 2226 No levels, no switch Levels + a threshold
if/else for every destination Logger edited for each new output Breaks open-closed Appender + Formatter interfaces
Comparing enums with > error: bad operand types for binary operator '>' (first type: Level) Enums aren't numbers level.compareTo(threshold) >= 0
Appender with the wrong method name error: ConsoleAppender is not abstract and does not override abstract method append(LogMessage) in Appender write is not append Implement the interface method (add @Override)
new Logger() in every class PaymentService DEBUG line missing Settings copied everywhere One Singleton manager
new LogManager() on an enum Singleton error: enum classes may not be instantiated That's the point of the enum LogManager.INSTANCE
Lowercase level in the config java.lang.IllegalArgumentException: No enum constant Level.debug valueOf is case-sensitive Level.valueOf(s.trim().toUpperCase())
One level for all appenders pager 1003 Same messages everywhere A level per chain link / per appender
Async with no shutdown if the app exits NOW, 200 lines are lost Daemon worker killed at exit Poison pill + join()

Mini project: a small logging library

TRACE below DEBUG, settings read from a real logging.properties file, a level per appender, a rolling file appender (a new file every maxLines lines), JSON in the file and plain text on the console, and an asynchronous writer thread with a clean shutdown.

import java.nio.file.*;
import java.time.LocalTime;
import java.util.*;
import java.util.concurrent.*;

// Mini project: a small logging library with TRACE, per-appender levels read from logging.properties,
// a rolling file appender, and an asynchronous dispatcher with a clean shutdown.
enum Level { TRACE, DEBUG, INFO, WARN, ERROR }

record LogMessage(LocalTime time, Level level, String logger, String thread, String text) {}

interface Formatter { String format(LogMessage m); }

interface Appender { Level level(); void append(LogMessage m); }

class ConsoleAppender implements Appender {
    private final Level level;  private final Formatter f;
    ConsoleAppender(Level level, Formatter f) { this.level = level;  this.f = f; }
    public Level level() { return level; }
    public void append(LogMessage m) { System.out.println(f.format(m)); }
}

class RollingFileAppender implements Appender {          // a new file every `maxLines` lines
    private final Level level;  private final Formatter f;  private final String base;  private final int maxLines;
    private int lines = 0, fileNo = 0;
    RollingFileAppender(Level level, Formatter f, String base, int maxLines) {
        this.level = level;  this.f = f;  this.base = base;  this.maxLines = maxLines; }
    public Level level() { return level; }
    public void append(LogMessage m) {
        if (lines == maxLines) { fileNo++;  lines = 0; }    // roll over to the next file
        try {
            Files.writeString(Path.of(base + "." + fileNo + ".log"), f.format(m) + "\n",
                              StandardOpenOption.CREATE, StandardOpenOption.APPEND);
            lines++;
        } catch (Exception e) { System.err.println("log write failed: " + e); }
    }
}

enum LogManager {
    INSTANCE;
    private volatile Level rootLevel = Level.INFO;
    private final List<Appender> appenders = new CopyOnWriteArrayList<>();
    private final BlockingQueue<LogMessage> queue = new ArrayBlockingQueue<>(10_000);
    private static final LogMessage STOP = new LogMessage(null, Level.ERROR, "", "", "<stop>");
    private Thread worker;
    private int dropped = 0;

    synchronized void configure(Path file) throws Exception {
        Properties p = new Properties();
        try (var in = Files.newBufferedReader(file)) { p.load(in); }
        rootLevel = Level.valueOf(p.getProperty("level", "INFO"));
        Formatter plain = m -> m.time().withNano(0) + " " + m.level() + " [" + m.thread() + "] " + m.logger() + ": " + m.text();
        Formatter json = m -> String.format("{\"level\":\"%s\",\"logger\":\"%s\",\"msg\":\"%s\"}", m.level(), m.logger(), m.text());
        appenders.clear();
        for (String name : p.getProperty("appenders", "console").split(",")) {
            name = name.trim();
            Level lv = Level.valueOf(p.getProperty(name + ".level", "TRACE"));
            switch (name) {
                case "console" -> appenders.add(new ConsoleAppender(lv, plain));
                case "file" -> appenders.add(new RollingFileAppender(lv, json, p.getProperty("file.name", "app"),
                                                                     Integer.parseInt(p.getProperty("file.maxLines", "1000"))));
                default -> throw new IllegalArgumentException("unknown appender: " + name);
            }
        }
        if (worker == null) {
            worker = new Thread(() -> {
                try {
                    for (LogMessage m = queue.take(); m != STOP; m = queue.take())
                        for (Appender a : appenders) if (m.level().compareTo(a.level()) >= 0) a.append(m);
                } catch (InterruptedException e) { Thread.currentThread().interrupt(); }
            }, "log-writer");
            worker.setDaemon(true);
            worker.start();
        }
    }
    Level level() { return rootLevel; }
    void submit(LogMessage m) { if (!queue.offer(m)) synchronized (this) { dropped++; } }
    void shutdown() throws InterruptedException { queue.put(STOP);  worker.join(); }
    synchronized int dropped() { return dropped; }
}

class Logger {
    private final String name;
    private Logger(String name) { this.name = name; }
    private static final Map<String, Logger> ALL = new ConcurrentHashMap<>();
    static Logger get(Class<?> c) { return ALL.computeIfAbsent(c.getSimpleName(), Logger::new); }
    void log(Level level, String text) {
        if (level.compareTo(LogManager.INSTANCE.level()) < 0) return;
        LogManager.INSTANCE.submit(new LogMessage(LocalTime.now(), level, name, Thread.currentThread().getName(), text));
    }
    void trace(String t) { log(Level.TRACE, t); }  void debug(String t) { log(Level.DEBUG, t); }
    void info(String t)  { log(Level.INFO, t); }   void warn(String t)  { log(Level.WARN, t); }
    void error(String t) { log(Level.ERROR, t); }
}

class PaymentService {
    private static final Logger log = Logger.get(PaymentService.class);
    void pay(int order) {
        log.trace("entering pay(" + order + ")");
        log.debug("calling bank for order " + order);
        if (order % 2 == 0) log.warn("bank slow for order " + order);
        if (order == 4) log.error("payment FAILED for order " + order);
        else log.info("order " + order + " paid");
    }
}

public class Main {
    public static void main(String[] args) throws Exception {
        Files.writeString(Path.of("logging.properties"), String.join("\n",
            "level=DEBUG", "appenders=console,file", "console.level=INFO",
            "file.level=WARN", "file.name=errors", "file.maxLines=2") + "\n");
        for (int i = 0; i < 3; i++) Files.deleteIfExists(Path.of("errors." + i + ".log"));
        LogManager.INSTANCE.configure(Path.of("logging.properties"));
        PaymentService payments = new PaymentService();
        for (int order = 1; order <= 5; order++) payments.pay(order);
        LogManager.INSTANCE.shutdown();
        for (int i = 0; i < 3; i++) {
            Path p = Path.of("errors." + i + ".log");
            if (Files.exists(p)) { System.out.println("--- " + p + " ---");  Files.readAllLines(p).forEach(System.out::println); }
        }
        System.out.println("dropped: " + LogManager.INSTANCE.dropped());
    }
}

Real output:

16:27:01 INFO [main] PaymentService: order 1 paid
16:27:01 WARN [main] PaymentService: bank slow for order 2
16:27:01 INFO [main] PaymentService: order 2 paid
16:27:01 INFO [main] PaymentService: order 3 paid
16:27:01 WARN [main] PaymentService: bank slow for order 4
16:27:01 ERROR [main] PaymentService: payment FAILED for order 4
16:27:01 INFO [main] PaymentService: order 5 paid
--- errors.0.log ---
{"level":"WARN","logger":"PaymentService","msg":"bank slow for order 2"}
{"level":"WARN","logger":"PaymentService","msg":"bank slow for order 4"}
--- errors.1.log ---
{"level":"ERROR","logger":"PaymentService","msg":"payment FAILED for order 4"}
dropped: 0

Console level INFO shows INFO and up; the file level WARN keeps only WARN and ERROR, and it rolled to errors.1.log after 2 lines. TRACE and DEBUG were logged in the code but filtered.

Practice

1. Add a TRACE level below DEBUG. What must change in Logger.log?

Answer

Only the enum: enum Level { TRACE, DEBUG, INFO, WARN, ERROR }. Because log compares with compareTo, which uses the order in the enum, nothing else changes. Add a trace(String) helper for convenience. See the mini project.

2. Write a RollingFileAppender that starts a new file every 1,000 lines.

Answer

Keep a line counter and a file number; when the counter reaches the limit, increase the file number and reset the counter, then write to base + "." + fileNo + ".log". See RollingFileAppender in the mini project (run with maxLines=2: errors.0.log got 2 lines, errors.1.log the next one).

3. Read the configuration from a real logging.properties file.

Answer
Properties p = new Properties();
try (var in = Files.newBufferedReader(Path.of("logging.properties"))) { p.load(in); }
Level level = Level.valueOf(p.getProperty("level", "INFO"));

The mini project reads level, appenders, console.level, file.level, file.name and file.maxLines this way.

4. Make the async logger carry LogMessage objects instead of String, and explain why.

Answer

BlockingQueue<LogMessage>: the time, level and thread are captured when log() is called, on the caller's thread. If the worker built them later, every line would say thread log-writer and the time of writing, not the time of the event. See LogManager.submit in the mini project (the console shows [main]).

5. In the chain Console(DEBUG) → File(INFO) → Pager(ERROR), a link handles a message and then stops the chain instead of passing it on. Which destinations does an ERROR reach?

Answer

Only the console: it's the first link and ERROR >= DEBUG, so it handles it and stops. That is the terminating form of Chain of Responsibility (episode 39), right for approvals, wrong for logging, where we want the pass-through form.

Quick quiz

Chain: Console(DEBUG) → File(INFO) → Pager(ERROR). We log WARN "bank slow for order 400". Which handlers write it? (a) only Console (b) Console and File (c) Console, File and Pager (d) only Pager

Answer

(b) Console and File. WARN is at least DEBUG and at least INFO, but below ERROR. The message travels the whole chain; two of the three links write it.

Interview questions

  1. Design a logging framework. What are the main classes? Logger (per class, by name), LogManager (one, holds configuration), Level, LogMessage, Appender (where), Formatter (how).
  2. Why log levels, and why are they ordered? To filter by seriousness with one comparison against a threshold.
  3. Which patterns appear? Singleton (manager), Strategy (appender, formatter), Chain of Responsibility (routing by level), Factory (getLogger), Producer-consumer (async).
  4. Why should the Logger not know about files and consoles? Open-Closed: new destinations become new Appender classes; Logger never changes.
  5. Why is the LogManager a Singleton? One place for the settings; change once, the whole app follows. An enum Singleton is thread-safe and can't be instantiated twice.
  6. What does asynchronous logging buy, and what does it cost? The request no longer waits for slow writes; the cost is possible loss on crash, a bounded queue that may drop or block, and the need for a clean shutdown.
  7. How do you avoid losing logs on shutdown? A poison pill and join(), or a JVM shutdown hook that calls it.
  8. Is your logger thread-safe? The level is volatile, the logger map is concurrent, the queue is a BlockingQueue, and only one worker thread writes to the appenders.
  9. How do you avoid the cost of building messages that are filtered out? Check the level first, or pass a Supplier<String> that is only called if the message will be written.
  10. What should never be logged? Passwords, OTPs, full card numbers, tokens; mask them.

Glossary

Term Meaning, with an example
Log A record of what a program did, written while it runs: ERROR [main] payment FAILED for order 742
Logging framework Reusable code that gives every class a logger and decides what, how and where to write
Logger The object a class calls to log: log.warn("bank slow"); one per class name
Log message (LogMessage) One entry: time, level, thread, text; here a record
Timestamp The time an event happened: 16:25:14
Production The live system real users use; no debugger there
Log levels Labels for seriousness, in order: DEBUG < INFO < WARN < ERROR
DEBUG Detail for developers: checking cart for order 742
INFO A normal event: order 742 placed
WARN Odd, not broken yet: bank slow for order 400
ERROR Something failed: payment FAILED for order 742
TRACE Even finer detail than DEBUG: entering pay(4)
Threshold The lowest level that gets through: threshold WARN drops DEBUG and INFO
enum A type with a fixed, ordered list of values: enum Level { DEBUG, INFO, WARN, ERROR }
compareTo (enum) Compares positions in the enum: WARN.compareTo(INFO) > 0
record A short data-only class: record LogMessage(Level level, String text) {}
Appender Where a line goes: console, file, network
Console appender Prints each line with System.out.println
File appender Adds each line to a file with Files.writeString(..., CREATE, APPEND)
Rolling file appender Starts a new file every N lines/MB/days: errors.0.log, errors.1.log
Formatter How a line looks: plain text or JSON
JSON Machine-readable text: {"level":"ERROR","msg":"payment FAILED"}
Lambda A short inline function: m -> m.level() + " " + m.text()
Open-Closed Principle Open for extension, closed for modification: add an Appender class, don't edit Logger
Singleton A class with exactly one object: enum LogManager { INSTANCE; }
Singleton logger / log manager The one object that owns the level and appenders for the whole app
Configuration Settings read from outside the code: level=DEBUG in logging.properties
Properties Java class that reads key=value text: p.getProperty("level")
volatile Makes a field's latest value visible to every thread at once
computeIfAbsent Gets the value for a key, creating it once if missing: same name → same Logger
Chain of Responsibility Handlers linked in a chain; a request is passed along it
Chain of Responsibility by level Each link has a minimum level; writes if serious enough, then passes on
Pass-through chain Every link may handle the request and still passes it on
Handler One link in the chain: ConsoleHandler(DEBUG)
Pager / on-call A device or app that wakes the engineer on duty for emergencies
Synchronous The caller waits until the work is done: ~1 s for 200 slow writes
Asynchronous logging with a queue log() only puts the message in a queue; a worker thread writes it later
BlockingQueue A thread-safe queue whose take() waits for an item
Bounded queue A queue with a maximum size: new ArrayBlockingQueue<>(10_000)
Worker thread A background thread that does the slow work
Daemon thread A thread Java doesn't wait for at exit: its queued work can be lost
Poison pill A special message that tells a worker to stop after everything before it
join() Waits until a thread has finished
Request id (correlation id) An id attached to every line of one request, to find them all
Log rotation Starting new log files by size or time, archiving old ones
Sampling Keeping only 1 in N messages of a noisy kind
Masking Hiding secrets in logs: card ****1234
java.util.logging The logging API built into the JDK (levels SEVERE ... FINEST)
Log4j 2 A popular Apache logging library (levels FATAL ... TRACE)

Summary

  • println everywhere buried the one failure among 3,001 lines, with no way to switch noise off.
  • Log levels (DEBUG < INFO < WARN < ERROR) and a threshold made the log quiet on demand, without deleting code.
  • LogMessage (what), Formatter (how) and Appender (where) made destinations and formats pluggable: console + JSON file.
  • new Logger() everywhere scattered the settings; a Singleton LogManager with configuration gave one switch.
  • The Chain of Responsibility gave each destination its own level: the pager went from 1003 rings to 1.
  • Asynchronous logging with a bounded BlockingQueue and one worker made logging fast; a poison pill + join() made sure nothing was lost.