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(). BecauseFormatterhas one method, a lambda can be aFormatter. - Rule: a failing appender must never crash the application.
FileAppendercatches 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
enumwith one value,INSTANCE: the JVM creates it once, thread-safely, and it cannot be created withnew(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
Propertiesclass readskey=valuelines likelevel=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. volatileon 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 sameLoggerobject.
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()returnsfalsewhen it's full (we drop and report; another policy is to wait withput()). - 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 callsjoin(), which waits until the worker has written everything before it. (s != STOPcompares 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
Levelclass (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
- Design a logging framework. What are the main classes?
Logger(per class, by name),LogManager(one, holds configuration),Level,LogMessage,Appender(where),Formatter(how). - Why log levels, and why are they ordered? To filter by seriousness with one comparison against a threshold.
- Which patterns appear? Singleton (manager), Strategy (appender, formatter), Chain of Responsibility (routing by level), Factory (
getLogger), Producer-consumer (async). - Why should the Logger not know about files and consoles? Open-Closed: new destinations become new
Appenderclasses;Loggernever changes. - Why is the LogManager a Singleton? One place for the settings; change once, the whole app follows. An
enumSingleton is thread-safe and can't be instantiated twice. - 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.
- How do you avoid losing logs on shutdown? A poison pill and
join(), or a JVM shutdown hook that calls it. - Is your logger thread-safe? The level is
volatile, the logger map is concurrent, the queue is aBlockingQueue, and only one worker thread writes to the appenders. - 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. - 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
printlneverywhere 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 SingletonLogManagerwith 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.