0
# Layouts
1

2
Layouts are responsible for formatting log events into the desired output format. Log4j Core provides numerous built-in layouts for various output formats including pattern-based text, JSON, XML, HTML, CSV, and protocol-specific formats.
3

4
## Capabilities
5

6
### Core Layout Interface
7

8
Base interface that all layouts must implement.
9

10
```java { .api }
11
/**
12
 * Core layout interface for formatting log events
13
 * @param <T> The type that the layout returns
14
 */
15
public interface Layout<T extends Serializable> extends Encodable {
16
    /**
17
     * Get header bytes for the layout output
18
     * @return Header bytes or null if no header
19
     */
20
    byte[] getHeader();
21
    
22
    /**
23
     * Get footer bytes for the layout output  
24
     * @return Footer bytes or null if no footer
25
     */
26
    byte[] getFooter();
27
    
28
    /**
29
     * Format log event to byte array
30
     * @param event LogEvent to format
31
     * @return Formatted event as byte array
32
     */
33
    byte[] toByteArray(LogEvent event);
34
    
35
    /**
36
     * Format log event to serializable object
37
     * @param event LogEvent to format
38
     * @return Formatted event as serializable object
39
     */
40
    T toSerializable(LogEvent event);
41
    
42
    /**
43
     * Get content type for this layout
44
     * @return Content type string
45
     */
46
    String getContentType();
47
    
48
    /**
49
     * Get content format descriptors
50
     * @return Map of format properties
51
     */
52
    Map<String, String> getContentFormat();
53
}
54
```
55

56
### Pattern Layout
57

58
Flexible pattern-based text formatting with customizable conversion patterns.
59

60
```java { .api }
61
/**
62
 * Create PatternLayout with builder pattern
63
 * @return PatternLayout.Builder instance
64
 */
65
public static PatternLayout.Builder newBuilder();
66

67
/**
68
 * Create default PatternLayout with standard pattern
69
 * @return PatternLayout with default pattern
70
 */
71
public static PatternLayout createDefaultLayout();
72

73
/**
74
 * Create PatternLayout with custom pattern
75
 * @param pattern Pattern string to use
76
 * @return PatternLayout with specified pattern
77
 */
78
public static PatternLayout createLayout(String pattern);
79

80
/**
81
 * PatternLayout configuration builder
82
 */
83
public static final class Builder implements org.apache.logging.log4j.core.util.Builder<PatternLayout> {
84
    public Builder withPattern(String pattern);
85
    public Builder withCharset(Charset charset);
86
    public Builder withAlwaysWriteExceptions(boolean alwaysWriteExceptions);
87
    public Builder withNoConsoleNoAnsi(boolean noConsoleNoAnsi);
88
    public Builder withHeader(String header);
89
    public Builder withFooter(String footer);
90
    public PatternLayout build();
91
}
92
```
93

94
**Usage Examples:**
95

96
```java
97
import org.apache.logging.log4j.core.layout.PatternLayout;
98
import java.nio.charset.StandardCharsets;
99

100
// Create default pattern layout
101
PatternLayout defaultLayout = PatternLayout.createDefaultLayout();
102

103
// Create custom pattern layout
104
PatternLayout customLayout = PatternLayout.newBuilder()
105
    .withPattern("%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n")
106
    .withCharset(StandardCharsets.UTF_8)
107
    .withAlwaysWriteExceptions(true)
108
    .build();
109

110
// Create layout with header and footer
111
PatternLayout headerFooterLayout = PatternLayout.newBuilder()
112
    .withPattern("%d{ISO8601} [%level] %logger - %msg%n")
113
    .withHeader("=== Application Start ===%n")
114
    .withFooter("=== Application End ===%n")
115
    .build();
116

117
// Common pattern examples
118
String timeStampPattern = "%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n";
119
String shortPattern = "%d{HH:mm:ss.SSS} [%level] %logger{20} - %msg%n";
120
String verbosePattern = "%d{ISO8601} [%thread] %level %logger{36}:%line - %msg%n";
121
```
122

123
### JSON Layout
124

125
Formats log events as JSON objects with configurable field inclusion.
126

127
```java { .api }
128
/**
129
 * Create JsonLayout with builder pattern
130
 * @return JsonLayout.Builder instance
131
 */
132
public static JsonLayout.Builder newBuilder();
133

134
/**
135
 * JsonLayout configuration builder
136
 */
137
public static final class Builder implements org.apache.logging.log4j.core.util.Builder<JsonLayout> {
138
    public Builder setCharset(Charset charset);
139
    public Builder setLocationInfo(boolean locationInfo);
140
    public Builder setProperties(boolean properties);
141
    public Builder setPropertiesAsList(boolean propertiesAsList);
142
    public Builder setComplete(boolean complete);
143
    public Builder setCompact(boolean compact);
144
    public Builder setEventEol(boolean eventEol);
145
    public Builder setHeader(String header);
146
    public Builder setFooter(String footer);
147
    public JsonLayout build();
148
}
149
```
150

151
**Usage Examples:**
152

153
```java
154
import org.apache.logging.log4j.core.layout.JsonLayout;
155

156
// Create basic JSON layout
157
JsonLayout jsonLayout = JsonLayout.newBuilder()
158
    .setLocationInfo(false)
159
    .setProperties(true)
160
    .setComplete(false)
161
    .setCompact(true)
162
    .build();
163

164
// Create verbose JSON layout with location info
165
JsonLayout verboseJsonLayout = JsonLayout.newBuilder()
166
    .setLocationInfo(true)
167
    .setProperties(true)
168
    .setPropertiesAsList(false)
169
    .setComplete(false)
170
    .setCompact(false)
171
    .setEventEol(true)
172
    .build();
173
```
174

175
### XML Layout
176

177
Formats log events as XML elements with configurable structure.
178

179
```java { .api }
180
/**
181
 * Create XmlLayout with builder pattern
182
 * @return XmlLayout.Builder instance
183
 */
184
public static XmlLayout.Builder newBuilder();
185

186
/**
187
 * XmlLayout configuration builder
188
 */
189
public static final class Builder implements org.apache.logging.log4j.core.util.Builder<XmlLayout> {
190
    public Builder setCharset(Charset charset);
191
    public Builder setLocationInfo(boolean locationInfo);
192
    public Builder setProperties(boolean properties);
193
    public Builder setComplete(boolean complete);
194
    public Builder setCompact(boolean compact);
195
    public Builder setHeader(String header);
196
    public Builder setFooter(String footer);
197
    public XmlLayout build();
198
}
199
```
200

201
### HTML Layout
202

203
Formats log events as HTML table rows with CSS styling support.
204

205
```java { .api }
206
/**
207
 * Create HtmlLayout with builder pattern
208
 * @return HtmlLayout.Builder instance
209
 */
210
public static HtmlLayout.Builder newBuilder();
211

212
/**
213
 * HtmlLayout configuration builder
214
 */
215
public static final class Builder implements org.apache.logging.log4j.core.util.Builder<HtmlLayout> {
216
    public Builder setCharset(Charset charset);
217
    public Builder setLocationInfo(boolean locationInfo);
218
    public Builder setTitle(String title);
219
    public Builder setContentType(String contentType);
220
    public HtmlLayout build();
221
}
222
```
223

224
**Usage Examples:**
225

226
```java
227
import org.apache.logging.log4j.core.layout.HtmlLayout;
228

229
// Create HTML layout for web display
230
HtmlLayout htmlLayout = HtmlLayout.newBuilder()
231
    .setTitle("Application Log")
232
    .setLocationInfo(true)
233
    .setContentType("text/html; charset=UTF-8")
234
    .build();
235
```
236

237
### CSV Layout
238

239
Formats log events as comma-separated values with configurable field selection.
240

241
```java { .api }
242
/**
243
 * Create CsvLayout with builder pattern  
244
 * @return CsvLayout.Builder instance
245
 */
246
public static CsvLayout.Builder newBuilder();
247

248
/**
249
 * CsvLayout configuration builder
250
 */
251
public static final class Builder implements org.apache.logging.log4j.core.util.Builder<CsvLayout> {
252
    public Builder setCharset(Charset charset);
253
    public Builder setDelimiter(char delimiter);
254
    public Builder setEscapeChar(char escapeChar);
255
    public Builder setFormat(CSVFormat format);
256
    public Builder setHeader(String header);
257
    public Builder setFooter(String footer);
258
    public CsvLayout build();
259
}
260
```
261

262
**Usage Examples:**
263

264
```java
265
import org.apache.logging.log4j.core.layout.CsvLayout;
266
import org.apache.commons.csv.CSVFormat;
267

268
// Create CSV layout with custom delimiter
269
CsvLayout csvLayout = CsvLayout.newBuilder()
270
    .setFormat(CSVFormat.DEFAULT.withHeader("Time", "Level", "Logger", "Message"))
271
    .setDelimiter('|')
272
    .build();
273
```
274

275
### GELF Layout
276

277
Formats log events in Graylog Extended Log Format for centralized logging.
278

279
```java { .api }
280
/**
281
 * Create GelfLayout with builder pattern
282
 * @return GelfLayout.Builder instance  
283
 */
284
public static GelfLayout.Builder newBuilder();
285

286
/**
287
 * GelfLayout configuration builder
288
 */
289
public static final class Builder implements org.apache.logging.log4j.core.util.Builder<GelfLayout> {
290
    public Builder setHost(String host);
291
    public Builder setCompressionType(CompressionType compressionType);
292
    public Builder setCompressionThreshold(int compressionThreshold);
293
    public Builder setIncludeStackTrace(boolean includeStackTrace);
294
    public Builder setIncludeThreadContext(boolean includeThreadContext);
295
    public Builder setIncludeNullDelimiter(boolean includeNullDelimiter);
296
    public GelfLayout build();
297
}
298
```
299

300
### YAML Layout
301

302
Formats log events in YAML format with readable structure.
303

304
```java { .api }
305
/**
306
 * Create YamlLayout with builder pattern
307
 * @return YamlLayout.Builder instance
308
 */
309
public static YamlLayout.Builder newBuilder();
310

311
/**
312
 * YamlLayout configuration builder
313
 */
314
public static final class Builder implements org.apache.logging.log4j.core.util.Builder<YamlLayout> {
315
    public Builder setCharset(Charset charset);
316
    public Builder setLocationInfo(boolean locationInfo);
317
    public Builder setProperties(boolean properties);
318
    public Builder setComplete(boolean complete);
319
    public Builder setHeader(String header);
320
    public Builder setFooter(String footer);
321
    public YamlLayout build();
322
}
323
```
324

325
### Syslog Layout
326

327
Formats log events according to syslog protocol standards.
328

329
```java { .api }
330
/**
331
 * Create SyslogLayout with builder pattern
332
 * @return SyslogLayout.Builder instance
333
 */
334
public static SyslogLayout.Builder newBuilder();
335

336
/**
337
 * SyslogLayout configuration builder
338
 */
339
public static final class Builder implements org.apache.logging.log4j.core.util.Builder<SyslogLayout> {
340
    public Builder setCharset(Charset charset);
341
    public Builder setFacility(Facility facility);
342
    public Builder setIncludeMdc(boolean includeMdc);
343
    public Builder setMdcId(String mdcId);
344
    public Builder setMdcPrefix(String mdcPrefix);
345
    public Builder setEventPrefix(String eventPrefix);
346
    public Builder setNewLine(boolean newLine);
347
    public SyslogLayout build();
348
}
349

350
/**
351
 * Syslog facility enumeration
352
 */
353
public enum Facility {
354
    KERN(0), USER(1), MAIL(2), DAEMON(3), AUTH(4), SYSLOG(5), 
355
    LPR(6), NEWS(7), UUCP(8), CRON(9), AUTHPRIV(10), FTP(11),
356
    LOCAL0(16), LOCAL1(17), LOCAL2(18), LOCAL3(19), 
357
    LOCAL4(20), LOCAL5(21), LOCAL6(22), LOCAL7(23);
358
}
359
```
360

361
### RFC5424 Layout
362

363
Formats log events according to RFC 5424 syslog standard.
364

365
```java { .api }
366
/**
367
 * Create Rfc5424Layout with builder pattern
368
 * @return Rfc5424Layout.Builder instance
369
 */
370
public static Rfc5424Layout.Builder newBuilder();
371

372
/**
373
 * Rfc5424Layout configuration builder
374
 */
375
public static final class Builder implements org.apache.logging.log4j.core.util.Builder<Rfc5424Layout> {
376
    public Builder setCharset(Charset charset);
377
    public Builder setFacility(Facility facility);
378
    public Builder setDefaultId(String defaultId);
379
    public Builder setEnterpriseNumber(int enterpriseNumber);
380
    public Builder setIncludeMdc(boolean includeMdc);
381
    public Builder setMdcId(String mdcId);
382
    public Builder setMdcPrefix(String mdcPrefix);
383
    public Builder setEventPrefix(String eventPrefix);
384
    public Builder setNewLine(boolean newLine);
385
    public Builder setAppName(String appName);
386
    public Builder setMessageId(String messageId);
387
    public Rfc5424Layout build();
388
}
389
```
390

391
## Pattern Layout Conversion Patterns
392

393
Common conversion patterns for PatternLayout:
394

395
### Date/Time Patterns
396
- `%d{yyyy-MM-dd HH:mm:ss.SSS}` - Full timestamp with milliseconds
397
- `%d{ISO8601}` - ISO 8601 format
398
- `%d{HH:mm:ss}` - Time only
399
- `%d{ABSOLUTE}` - Absolute time format
400

401
### Logger and Level Patterns
402
- `%logger{36}` - Logger name truncated to 36 characters
403
- `%c{1}` - Short logger name (last component only)
404
- `%level` - Log level (INFO, DEBUG, etc.)
405
- `%-5level` - Left-aligned level with fixed width
406

407
### Message and Exception Patterns
408
- `%msg` or `%m` - Log message
409
- `%ex` - Exception stack trace
410
- `%ex{short}` - Shortened exception
411
- `%rEx` - Root cause exception
412

413
### Thread and Location Patterns
414
- `%thread` or `%t` - Thread name
415
- `%location` or `%l` - Full location info
416
- `%C{1}` - Simple class name
417
- `%M` - Method name
418
- `%L` - Line number
419
- `%F` - File name
420

421
### Formatting Patterns
422
- `%n` - Platform-specific line separator
423
- `%highlight{pattern}` - Highlight based on level
424
- `%style{pattern}{color}` - Apply ANSI color
425
- `%-20logger` - Left-aligned logger with padding