How Logback Turns a Simple Log Call into a Fully Processed Log Entry

Introduction

Logback is a widely used open‑source logging framework for Java applications. Although a single line such as logger.info("Hello world.") appears trivial, a complex chain of components processes the request before the text reaches its destination.

Key Concepts

LoggingEvent – the object that encapsulates all information about a log request, including thread name, timestamp, level, logger name, message, and any attached exception.

Logger – the entry point for logging. Loggers are hierarchical (e.g., com.foo is the parent of com.foo.Bar) and share configuration with their ancestors; the root logger sits at the top.

Appender – represents a destination such as console, file, socket, or database. A logger may have multiple appenders attached.

Layout – formats a LoggingEvent into a string according to a pattern, for example %-4relative [%thread] %-5level %logger{32} - %msg%n.

Logging Workflow

Obtain a Logger instance via LoggerFactory.getLogger("wombat"). Repeated calls with the same name return the same object.

Invoke a logging method, e.g., logger.info("Hello world.").

The request first passes through the TurboFilter chain. If the filter returns DENY, the request is dropped; NEUTRAL lets processing continue; ACCEPT skips the next step.

The logger’s effective level is compared with the event’s level. If the event level is lower, the request is ignored.

When allowed, Logback creates a LoggingEvent containing thread, timestamp, level, logger name, message, and optional throwable.

All attached appenders receive the event. Each appender runs its own filter chain (class Filter) that can again accept, deny, or pass the event.

The appender’s Encoder invokes the configured Layout (or pattern) to turn the event into a formatted string.

The formatted string is written to the appender’s destination (file, console, etc.).

The overall flow is illustrated in the diagram below:

RollingFileAppender and Extra Work

When logging to a file, Logback can rotate files based on size, time, or both using RollingFileAppender together with SizeAndTimeBasedRollingPolicy (which implements both RollingPolicy and TriggeringPolicy). A typical XML configuration looks like:

<appender name="ERROR" class="ch.qos.logback.core.rolling.RollingFileAppender">
  <file>${LOG_PATH}/error.log</file>
  <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
    <level>ERROR</level>
  </filter>
  <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
    <!-- daily rollover -->
    <fileNamePattern>${LOG_PATH}/%d{yyyy-MM-dd}/error-%d{yyyy-MM-dd}-%i.log.gz</fileNamePattern>
    <!-- each file should be at most 100MB -->
    <maxFileSize>100MB</maxFileSize>
    <!-- keep 60 days' worth of history capped at 3GB total size -->
    <maxHistory>60</maxHistory>
    <totalSizeCap>3GB</totalSizeCap>
  </rollingPolicy>
  <encoder>
    <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %caller{1} - %msg%n</pattern>
    <charset>utf8</charset>
  </encoder>
</appender>

The appender’s subAppend() method contains the logic that triggers a rollover when the size or time condition is met:

protected void subAppend(E event) {
    synchronized (triggeringPolicy) {
        if (triggeringPolicy.isTriggeringEvent(currentlyActiveFile, event)) {
            rollover();
        }
    }
    super.subAppend(event);
}

Two main rollover strategies are supported:

Size‑based rollover : When the active file exceeds maxFileSize, Logback archives the current file and starts a new one.

Time‑based rollover : At a configured time (e.g., daily at midnight) Logback rolls over the file, archives it, and may delete old archives according to maxHistory and totalSizeCap. Cleanup runs in a background thread, as shown in the ArchiveRemoverRunnable snippet.

In earlier versions, a bug caused maxHistory cleanup to fail for applications that only run during the day because the time‑based trigger was set at application start. The issue was fixed by adding the cleanHistoryOnStart attribute to TimeBasedRollingPolicy, which forces history cleanup when the application starts.

Conclusion

The article has detailed how Logback processes a simple log call, from logger acquisition through filtering, event creation, formatting, and output, and has explained the additional responsibilities of RollingFileAppender for file rotation and cleanup. Understanding these internals helps developers configure Logback efficiently and troubleshoot logging‑related problems.