CSE Roadmap

Core tier · about 4 hours · 6 parts

Part 4 of 6 · 5 min read

The code

Level checks, parent chain and appenders.

The record and the two small interfaces:

enum Level { TRACE, DEBUG, INFO, WARN, ERROR }

record LogRecord(Instant time, Level level, String logger, String message, Throwable error) {}

interface Formatter { String format(LogRecord r); }

interface Appender extends AutoCloseable {
    void append(LogRecord r);
    default void close() {}
}

The logger finds its effective level by walking up to the first ancestor that has one, and dispatches to every appender on the way up:

class Logger {
    private final String name; private final Logger parent;
    private volatile Level level;
    private final List<Appender> appenders = new CopyOnWriteArrayList<>();
    private final Supplier<Instant> clock;

    Level effectiveLevel() {
        for (Logger l = this; l != null; l = l.parent) if (l.level != null) return l.level;
        return Level.INFO;
    }
    boolean enabled(Level l) { return l.compareTo(effectiveLevel()) >= 0; }

    void log(Level l, String msg, Throwable t) {
        if (enabled(l)) dispatch(new LogRecord(clock.get(), l, name, msg, t));
    }
    void log(Level l, Supplier<String> msg) {                 // message built only if needed
        if (enabled(l)) dispatch(new LogRecord(clock.get(), l, name, msg.get(), null));
    }
    private void dispatch(LogRecord r) {
        for (Logger lg = this; lg != null; lg = lg.parent)
            for (Appender a : lg.appenders) {
                try { a.append(r); } catch (RuntimeException e) { /* never break the caller */ }
            }
    }
}

Three details deserve a sentence each. The Supplier overload means an expensive message, such as a large object turned into text, is built only when the level is on. The list of appenders is a CopyOnWriteArrayList, so a thread can add an appender while others are logging without a lock (Level 4, module 2 used it for the same reason). The level is volatile, so a change made by one thread is seen by the others (Level 5, module 3).

The manager builds the parent chain from the dotted name:

synchronized Logger get(String name) {
    Logger l = loggers.get(name);
    if (l != null) return l;
    int dot = name.lastIndexOf('.');
    Logger parent = dot < 0 ? root : get(name.substring(0, dot));
    l = new Logger(name, parent, clock);
    loggers.put(name, l);
    return l;
}

Asking for "app.db.pool" creates "app.db.pool", "app.db" and "app" if they do not exist, each with its parent set.

A run. The root logger has level info and a memory appender. The logger "app.db" has its own appender that prints only level and message.

Action Result
app.db.pool logs info "connected" root appender gets the full line, the "app.db" appender gets INFO:connected
app.db.pool logs debug "hidden" dropped, since the effective level is info
app.web logs error "failed" with a cause root line ends with "(boom)"
Set the level of "app.db" to debug, then log debug now visible, and app.db.pool reports effective level DEBUG, while app.web still reports INFO
Log debug with a supplier, then error with a supplier the supplier ran once, for the error only
Add an appender that throws, then log info the line still reaches the other appender

The asynchronous appender wraps another appender with a bounded queue and one worker thread. It follows the producer-consumer pattern of Level 5, module 4.

class AsyncAppender implements Appender {
    private final Appender target; private final BlockingQueue<LogRecord> q;
    private final Thread worker; private final AtomicLong dropped = new AtomicLong();
    private static final LogRecord STOP = new LogRecord(Instant.EPOCH, Level.TRACE, "", "", null);

    AsyncAppender(Appender target, int capacity) {
        this.target = target; q = new ArrayBlockingQueue<>(capacity);
        worker = new Thread(() -> {
            try {
                while (true) {
                    LogRecord r = q.take();
                    if (r == STOP) break;
                    try { target.append(r); } catch (RuntimeException e) { dropped.incrementAndGet(); }
                }
            } catch (InterruptedException e) { Thread.currentThread().interrupt(); }
        });
        worker.start();
    }
    public void append(LogRecord r) { if (!q.offer(r)) dropped.incrementAndGet(); }   // never blocks
    public void close() { try { q.put(STOP); worker.join(); } catch (InterruptedException e) { Thread.currentThread().interrupt(); } target.close(); }
}

offer returns false at once when the queue is full, so the caller never waits, and the lost record is counted. close puts a stop marker (the poison pill of Level 5, module 4) and waits for the worker, so every queued record is written before the program exits.

Two runs against a target that takes 5 ms per record. With a queue of 10 and 100 quick log calls, about 10 records were written and about 90 were dropped, so the two always add to 100. The exact split varies, since it depends on timing. The first line written was the first sent, so order is kept. With a queue of 1000 and 200 calls, all 200 were written and none dropped.

Check yourself: 1. How does the logger find its effective level? 2. Why is the message given as a supplier? 3. What does AsyncAppender.append do when the queue is full?