0
# Layout System
1

2
Flexible layout system for customizing log message formatting with timezone support and custom pattern converters. The layout system provides both default Dropwizard layouts and extensible factories for creating custom layouts.
3

4
## Capabilities
5

6
### LayoutFactory Interface
7

8
Base interface for creating Logback layouts with timezone support.
9

10
```java { .api }
11
/**
12
 * Interface for creating Logback layouts
13
 * @param <E> The type of log event
14
 */
15
public interface LayoutFactory<E extends DeferredProcessingAware> {
16
    /**
17
     * Creates a {@link PatternLayoutBase} of type E
18
     * @param context the Logback context
19
     * @param timeZone the TimeZone
20
     * @return a new {@link PatternLayoutBase}
21
     */
22
    PatternLayoutBase<E> build(LoggerContext context, TimeZone timeZone);
23
}
24
```
25

26
### DiscoverableLayoutFactory Interface
27

28
Jackson-discoverable layout factory interface enabling polymorphic configuration of custom layouts.
29

30
```java { .api }
31
/**
32
 * Jackson-discoverable layout factory for building Logback layouts
33
 * @param <E> The type of log event
34
 */
35
@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "type")
36
public interface DiscoverableLayoutFactory<E extends DeferredProcessingAware> extends Discoverable {
37
    /**
38
     * Creates a {@link LayoutBase} of type E
39
     * @param context the Logback context
40
     * @param timeZone the TimeZone
41
     * @return a new {@link LayoutBase}
42
     */
43
    LayoutBase<E> build(LoggerContext context, TimeZone timeZone);
44
}
45
```
46

47
### DropwizardLayoutFactory
48

49
Factory for creating the default Dropwizard layout instances with standard formatting and custom converters.
50

51
```java { .api }
52
/**
53
 * Factory for creating DropwizardLayout instances
54
 */
55
public class DropwizardLayoutFactory implements LayoutFactory<ILoggingEvent> {
56
    /**
57
     * Build a DropwizardLayout instance
58
     * @param context the Logback logger context
59
     * @param timeZone the timezone for timestamp formatting
60
     * @return configured DropwizardLayout
61
     */
62
    @Override
63
    public PatternLayoutBase<ILoggingEvent> build(LoggerContext context, TimeZone timeZone);
64
}
65
```
66

67
### DropwizardLayout
68

69
Default Dropwizard log layout extending PatternLayout with custom converters and exception formatting.
70

71
```java { .api }
72
/**
73
 * Default Dropwizard log layout with custom converters
74
 */
75
public class DropwizardLayout extends PatternLayout {
76
    /**
77
     * Default constructor that sets up custom converters and formatting
78
     */
79
    public DropwizardLayout();
80
    
81
    /**
82
     * Get the default Dropwizard log pattern
83
     * @return the default pattern string
84
     */
85
    public static String getDefaultPattern();
86
    
87
    /**
88
     * Set up custom throwable converters
89
     */
90
    private void setupCustomConverters();
91
}
92
```
93

94
**Features:**
95

96
- **Custom Throwable Converters**: Registers custom converters for exception formatting
97
  - `dwEx` - Prefixed throwable converter
98
  - `dwREx` - Prefixed root-cause-first throwable converter  
99
  - `dwXEx` - Prefixed extended throwable converter
100
- **Exception Prefixing**: Automatically prefixes exception stack traces with `!` character
101
- **ISO8601 Timestamps**: Uses ISO8601 format for timestamps by default
102
- **Pattern Header Disabled**: Disables pattern layout headers for cleaner output
103

104
**Usage Example:**
105

106
```java
107
DropwizardLayoutFactory layoutFactory = new DropwizardLayoutFactory();
108
LoggerContext context = (LoggerContext) LoggerFactory.getILoggerFactory();
109
TimeZone timeZone = TimeZone.getTimeZone("UTC");
110
Layout<ILoggingEvent> layout = layoutFactory.build(context, timeZone);
111

112
// Or create directly
113
DropwizardLayout layout = new DropwizardLayout();
114
layout.setContext(context);
115
layout.start();
116
```
117

118
### Custom Throwable Converters
119

120
Specialized converter classes for formatting exception stack traces with consistent prefixing.
121

122
#### PrefixedThrowableProxyConverter
123

124
Base converter that prefixes stack traces with a configurable prefix character.
125

126
```java { .api }
127
/**
128
 * Prefixes stack traces with configurable prefix
129
 */
130
public class PrefixedThrowableProxyConverter extends ThrowableProxyConverter {
131
    public static final String PATTERN = "([\\da-f]{8}-[\\da-f]{4}-[\\da-f]{4}-[\\da-f]{4}-[\\da-f]{12})";
132
    public static final String PREFIX = "! ";
133
    
134
    /**
135
     * Convert throwable to formatted string with prefix
136
     * @param event the logging event containing the throwable
137
     * @return formatted string with prefixed lines
138
     */
139
    @Override
140
    public String convert(ILoggingEvent event);
141
}
142
```
143

144
#### PrefixedExtendedThrowableProxyConverter
145

146
Extended throwable converter that includes packaging data and prefixing.
147

148
```java { .api }
149
/**
150
 * Extended throwable converter with packaging data and prefix
151
 */
152
public class PrefixedExtendedThrowableProxyConverter extends PrefixedThrowableProxyConverter {
153
    /**
154
     * Add extra packaging data to the output
155
     * @param builder the StringBuilder to append to
156
     * @param step the stack trace element proxy containing packaging information
157
     */
158
    @Override
159
    protected void extraData(StringBuilder builder, StackTraceElementProxy step);
160
}
161
```
162

163
#### PrefixedRootCauseFirstThrowableProxyConverter
164

165
Root-cause-first throwable converter with prefixing for easier debugging.
166

167
```java { .api }
168
/**
169
 * Root-cause-first throwable converter with prefixing
170
 */
171
public class PrefixedRootCauseFirstThrowableProxyConverter extends RootCauseFirstThrowableProxyConverter {
172
    /**
173
     * Convert throwable proxy to formatted string showing root cause first with prefix
174
     * @param tp the throwable proxy to convert
175
     * @return formatted string with root cause first and prefixed lines
176
     */
177
    @Override
178
    protected String throwableProxyToString(IThrowableProxy tp);
179
}
180
```
181

182
**Usage in Custom Layouts:**
183

184
```java
185
// Register custom converters in a custom layout
186
public class CustomLayout extends PatternLayout {
187
    @Override
188
    public void start() {
189
        // Register the custom converters
190
        getContext().putProperty("CONVERTER_CLASS_dwEx", 
191
            PrefixedThrowableProxyConverter.class.getName());
192
        getContext().putProperty("CONVERTER_CLASS_dwREx", 
193
            PrefixedRootCauseFirstThrowableProxyConverter.class.getName());
194
        getContext().putProperty("CONVERTER_CLASS_dwXEx", 
195
            PrefixedExtendedThrowableProxyConverter.class.getName());
196
        
197
        super.start();
198
    }
199
}
200
```
201

202
### Pattern Examples
203

204
**Default Dropwizard Pattern:**
205
```
206
%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n%dwEx
207
```
208

209
**Console Pattern with Colors:**
210
```
211
%cyan(%d{HH:mm:ss.SSS}) %gray([%thread]) %highlight(%-5level) %magenta(%logger{36}) - %msg%n%dwEx
212
```
213

214
**JSON Layout Pattern:**
215
```
216
{"timestamp":"%d{yyyy-MM-dd'T'HH:mm:ss.SSS'Z'}","thread":"%thread","level":"%-5level","logger":"%logger","message":"%msg","exception":"%dwEx"}%n
217
```
218

219
**Syslog Pattern:**
220
```
221
%msg%n%dwEx
222
```
223

224
**File Pattern with Extended Info:**
225
```
226
%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} [%X{requestId}] - %msg%n%dwXEx
227
```