Deep Dive into Log4j Layouts

Layouts in Log4j are responsible for formatting log messages before they are sent to their final destination, such as the console, a file, or a remote server. They determine how the log messages appear, including which elements (like timestamps, log levels, and messages) are included in the output and how they are structured.

For example, a layout might specify that each log message should include a timestamp, the severity level, and the actual message content.

In this post, we’ll see in detail the different types of Layouts and how to configure them in Log4j.

Configuration of Layouts in Log4j

Layouts in Log4j are defined within the Appenders section. We’ll see in detail later in this post the specifics of how to define a layout.

Each Appender represents a destination for our logs and has a layout associated. And then, in the loggers section, each logger is associated to an Appender, and hence to a layout. See below the default log42.xml in Mule where the file appender has a PatternLayout defined. That’s the XML item that specifies what info is logged and in which format by default in Mule. That’s the reason why you see the logs in Cloudhub with that format.

Log4j provides several built-in layouts which allow us to customize how the log messages appear. Each of these built-in layouts serve different purposes. The most common built-in layouts in Log4j are:

PatternLayout
HTMLLayout
XMLLayout
JSONLayout
SimpleLayout

Built-in Layouts in Log4j

1. PatternLayout

PatternLayout is the most commonly used layout in Log4j due to its flexibility. It is highly customizable and supports a wide range of specifiers.

PatternLayout is the default layout that we'll find in our Mule apps if we don't change anything in the log4j2.xml file.

It allows us to define a custom format for our log messages using a conversion pattern string. This string can include various placeholders (conversion specifiers) that represent different parts of the log event, such as the date, log level, thread name, and message.

The format and the logged info in this layout is defined by a conversion pattern.

For example, let’s break down the conversion pattern = "%-5p [%t]: %m%n".

In this conversion pattern we can see the following conversion specifiers, all of them starting with %.

%5p – the "p" is a conversion character and represents the level or priority in the log. The “5” in the “%5p” is a format modifier and sets the width of the field to 5 characters. And the -5p represents another format modifier and means it should be left justified.
[%t] - the "t" is the conversion character and represents the name of the thread that generated the logging event
%m - the “m” conversion character represents the message of the log
%n - the “n” conversion character represents a new line of text

The output could be something like this:

DEBUG [main]: Message 1
WARN [main]: Message 2

If you want to know more about the PatternLayout have a look at this post, where we will Break down the Log4j PatternLayout

2. HTMLLayout

HTMLLayout formats log messages into an HTML table, making it useful for generating logs that can be easily viewed in a web browser.

Key Features:

Produces an HTML document with a table of log events.
Includes headers and colors to differentiate log levels.

3. XMLLayout

XMLLayout formats log messages as XML documents. This is useful for systems that require structured data or for integration with other tools that process XML.

Key Features:

Outputs log events in XML format.
Provides structured, machine-readable logs.

4. JSONLayout

JSONLayout is another powerful layout in Log4j2 that formats log messages in JSON format. This layout is particularly useful when logs are ingested by systems that process JSON, such as ELK (Elasticsearch, Logstash, Kibana) stacks or other centralized logging solutions.

Key Features of JSONLayout

Structured Logging: Log messages are structured in JSON format, making it easier for log processing systems to parse and analyze the data.
Customizable Fields: You can include or exclude certain fields, such as timestamps, log levels, thread names, and more.
Easy Integration: Ideal for integration with modern logging and monitoring tools that work with JSON data.

Basic Configuration Example

Here’s a simple example of using JSONLayout in a log4j2.xml file:

<Appenders>
  <File name="FileAppender" fileName="logs/app.json">
    <JSONLayout compact="true" eventEol="true"/>
  </File>
</Appenders>

compact="true": Removes unnecessary whitespace, making the JSON more compact.
eventEol="true": Adds a newline after each JSON event, making it easier to read when viewed in a text editor.

In our next post, we'll dive deeper and Break down the Log4j JSONLayout.

Custom Layouts

If the built-in layouts don't meet your needs, you can create a custom layout by extending org.apache.log4j.Layout or implementing org.apache.log4j.spi.LoggingEvent. In Log4j 2.x, you'd implement org.apache.logging.log4j.core.Layout.