0
# Appenders
1

2
Appenders are responsible for delivering log events to their destination. Log4j Core provides numerous built-in appenders for various output targets including files, consoles, databases, network sockets, and message queues.
3

4
## Capabilities
5

6
### Core Appender Interface
7

8
Base interface that all appenders must implement.
9

10
```java { .api }
11
/**
12
 * Core appender interface for handling log events
13
 */
14
public interface Appender extends LifeCycle {
15
    /**
16
     * Append a log event to the destination
17
     * @param event LogEvent to append
18
     */
19
    void append(LogEvent event);
20
    
21
    /**
22
     * Get the appender name
23
     * @return Appender name
24
     */
25
    String getName();
26
    
27
    /**
28
     * Get the layout used by this appender
29
     * @return Layout instance or null
30
     */
31
    Layout<? extends Serializable> getLayout();
32
    
33
    /**
34
     * Check if exceptions should be ignored
35
     * @return true if exceptions are ignored
36
     */
37
    boolean ignoreExceptions();
38
    
39
    /**
40
     * Get the error handler
41
     * @return ErrorHandler instance
42
     */
43
    ErrorHandler getHandler();
44
    
45
    /**
46
     * Set the error handler
47
     * @param handler ErrorHandler to set
48
     */
49
    void setHandler(ErrorHandler handler);
50
}
51
```
52

53
### Console Appender
54

55
Writes log events to System.out or System.err.
56

57
```java { .api }
58
/**
59
 * Create ConsoleAppender with builder pattern
60
 * @return ConsoleAppender.Builder instance
61
 */
62
public static ConsoleAppender.Builder newBuilder();
63

64
/**
65
 * ConsoleAppender configuration builder
66
 */
67
public static final class Builder implements org.apache.logging.log4j.core.util.Builder<ConsoleAppender> {
68
    public Builder setName(String name);
69
    public Builder setLayout(Layout<? extends Serializable> layout);
70
    public Builder setFilter(Filter filter);
71
    public Builder setTarget(Target target);
72
    public Builder setFollow(boolean follow);
73
    public Builder setDirect(boolean direct);
74
    public Builder setBufferedIo(boolean bufferedIo);
75
    public Builder setBufferSize(int bufferSize);
76
    public ConsoleAppender build();
77
}
78

79
/**
80
 * Console target enumeration
81
 */
82
public enum Target {
83
    SYSTEM_OUT("SYSTEM_OUT"),
84
    SYSTEM_ERR("SYSTEM_ERR");
85
}
86
```
87

88
**Usage Examples:**
89

90
```java
91
import org.apache.logging.log4j.core.appender.ConsoleAppender;
92
import org.apache.logging.log4j.core.layout.PatternLayout;
93

94
// Create console appender to System.out
95
ConsoleAppender consoleAppender = ConsoleAppender.newBuilder()
96
    .setName("Console")
97
    .setTarget(ConsoleAppender.Target.SYSTEM_OUT)
98
    .setLayout(PatternLayout.createDefaultLayout())
99
    .build();
100

101
// Create console appender to System.err with custom layout
102
PatternLayout layout = PatternLayout.newBuilder()
103
    .withPattern("%d{yyyy-MM-dd HH:mm:ss} [%level] %logger{36} - %msg%n")
104
    .build();
105

106
ConsoleAppender errorAppender = ConsoleAppender.newBuilder()
107
    .setName("ErrorConsole")
108
    .setTarget(ConsoleAppender.Target.SYSTEM_ERR)
109
    .setLayout(layout)
110
    .build();
111
```
112

113
### File Appender
114

115
Writes log events to a file.
116

117
```java { .api }
118
/**
119
 * Create FileAppender with builder pattern
120
 * @return FileAppender.Builder instance
121
 */
122
public static FileAppender.Builder newBuilder();
123

124
/**
125
 * FileAppender configuration builder
126
 */
127
public static final class Builder implements org.apache.logging.log4j.core.util.Builder<FileAppender> {
128
    public Builder setName(String name);
129
    public Builder setLayout(Layout<? extends Serializable> layout);
130
    public Builder setFilter(Filter filter);
131
    public Builder withFileName(String fileName);
132
    public Builder withAppend(boolean append);
133
    public Builder withBufferedIo(boolean bufferedIo);
134
    public Builder withBufferSize(int bufferSize);
135
    public Builder setImmediateFlush(boolean immediateFlush);
136
    public FileAppender build();
137
}
138
```
139

140
**Usage Examples:**
141

142
```java
143
import org.apache.logging.log4j.core.appender.FileAppender;
144

145
// Create basic file appender
146
FileAppender fileAppender = FileAppender.newBuilder()
147
    .setName("FileAppender")
148
    .withFileName("application.log")
149
    .withAppend(true)
150
    .setLayout(PatternLayout.createDefaultLayout())
151
    .build();
152

153
// Create file appender with buffering
154
FileAppender bufferedAppender = FileAppender.newBuilder()
155
    .setName("BufferedFile")
156
    .withFileName("logs/app.log")
157
    .withBufferedIo(true)
158
    .withBufferSize(8192)
159
    .setImmediateFlush(false)
160
    .setLayout(layout)
161
    .build();
162
```
163

164
### Rolling File Appender
165

166
File appender that rolls over based on size, time, or other policies.
167

168
```java { .api }
169
/**
170
 * Create RollingFileAppender with builder pattern
171
 * @return RollingFileAppender.Builder instance
172
 */
173
public static RollingFileAppender.Builder newBuilder();
174

175
/**
176
 * RollingFileAppender configuration builder
177
 */
178
public static final class Builder implements org.apache.logging.log4j.core.util.Builder<RollingFileAppender> {
179
    public Builder setName(String name);
180
    public Builder setLayout(Layout<? extends Serializable> layout);
181
    public Builder setFilter(Filter filter);
182
    public Builder withFileName(String fileName);
183
    public Builder withFilePattern(String filePattern);
184
    public Builder withPolicy(TriggeringPolicy policy);
185
    public Builder withStrategy(RolloverStrategy strategy);
186
    public Builder withAppend(boolean append);
187
    public RollingFileAppender build();
188
}
189
```
190

191
**Usage Examples:**
192

193
```java
194
import org.apache.logging.log4j.core.appender.RollingFileAppender;
195
import org.apache.logging.log4j.core.appender.rolling.SizeBasedTriggeringPolicy;
196
import org.apache.logging.log4j.core.appender.rolling.DefaultRolloverStrategy;
197

198
// Create size-based rolling appender
199
SizeBasedTriggeringPolicy policy = SizeBasedTriggeringPolicy.createPolicy("10MB");
200
DefaultRolloverStrategy strategy = DefaultRolloverStrategy.newBuilder()
201
    .withMax("10")
202
    .build();
203

204
RollingFileAppender rollingAppender = RollingFileAppender.newBuilder()
205
    .setName("RollingFile")
206
    .withFileName("logs/app.log")
207
    .withFilePattern("logs/app-%i.log.gz")
208
    .withPolicy(policy)
209
    .withStrategy(strategy)
210
    .withAppend(true)
211
    .setLayout(PatternLayout.createDefaultLayout())
212
    .build();
213
```
214

215
### Async Appender
216

217
Wraps other appenders to provide asynchronous logging.
218

219
```java { .api }
220
/**
221
 * Create AsyncAppender with builder pattern
222
 * @return AsyncAppender.Builder instance
223
 */
224
public static AsyncAppender.Builder newBuilder();
225

226
/**
227
 * AsyncAppender configuration builder
228
 */
229
public static final class Builder implements org.apache.logging.log4j.core.util.Builder<AsyncAppender> {
230
    public Builder setName(String name);
231
    public Builder setFilter(Filter filter);
232
    public Builder setAppenderRefs(AppenderRef[] appenderRefs);
233
    public Builder setBufferSize(int bufferSize);
234
    public Builder setShutdownTimeout(long shutdownTimeout);
235
    public Builder setIncludeLocation(boolean includeLocation);
236
    public Builder setBlockingQueueFactory(BlockingQueueFactory<LogEvent> blockingQueueFactory);
237
    public AsyncAppender build();
238
}
239
```
240

241
**Usage Examples:**
242

243
```java
244
import org.apache.logging.log4j.core.appender.AsyncAppender;
245
import org.apache.logging.log4j.core.config.AppenderRef;
246

247
// Create async wrapper for file appender
248
AppenderRef ref = AppenderRef.createAppenderRef("FileAppender", null, null);
249
AppenderRef[] refs = new AppenderRef[] { ref };
250

251
AsyncAppender asyncAppender = AsyncAppender.newBuilder()
252
    .setName("AsyncFile")
253
    .setAppenderRefs(refs)
254
    .setBufferSize(2048)
255
    .setShutdownTimeout(3000)
256
    .setIncludeLocation(false)
257
    .build();
258
```
259

260
### Socket Appender
261

262
Sends log events over TCP sockets.
263

264
```java { .api }
265
/**
266
 * Create SocketAppender with builder pattern
267
 * @return SocketAppender.Builder instance
268
 */
269
public static SocketAppender.Builder newBuilder();
270

271
/**
272
 * SocketAppender configuration builder
273
 */
274
public static final class Builder implements org.apache.logging.log4j.core.util.Builder<SocketAppender> {
275
    public Builder setName(String name);
276
    public Builder setLayout(Layout<? extends Serializable> layout);
277
    public Builder setFilter(Filter filter);
278
    public Builder withHost(String host);
279
    public Builder withPort(int port);
280
    public Builder withProtocol(Protocol protocol);
281
    public Builder withReconnectDelayMillis(int reconnectDelayMillis);
282
    public SocketAppender build();
283
}
284
```
285

286
### SMTP Appender
287

288
Sends log events via email.
289

290
```java { .api }
291
/**
292
 * Create SmtpAppender with builder pattern
293
 * @return SmtpAppender.Builder instance
294
 */
295
public static SmtpAppender.Builder newBuilder();
296

297
/**
298
 * SmtpAppender configuration builder
299
 */
300
public static final class Builder implements org.apache.logging.log4j.core.util.Builder<SmtpAppender> {
301
    public Builder setName(String name);
302
    public Builder setLayout(Layout<? extends Serializable> layout);
303
    public Builder setFilter(Filter filter);
304
    public Builder setTo(String to);
305
    public Builder setCc(String cc);
306
    public Builder setBcc(String bcc);
307
    public Builder setFrom(String from);
308
    public Builder setSubject(String subject);
309
    public Builder setSmtpHost(String smtpHost);
310
    public Builder setSmtpPort(int smtpPort);
311
    public SmtpAppender build();
312
}
313
```
314

315
### HTTP Appender
316

317
Sends log events via HTTP requests.
318

319
```java { .api }
320
/**
321
 * Create HttpAppender with builder pattern
322
 * @return HttpAppender.Builder instance
323
 */
324
public static HttpAppender.Builder newBuilder();
325

326
/**
327
 * HttpAppender configuration builder
328
 */
329
public static final class Builder implements org.apache.logging.log4j.core.util.Builder<HttpAppender> {
330
    public Builder setName(String name);
331
    public Builder setLayout(Layout<? extends Serializable> layout);
332
    public Builder setFilter(Filter filter);
333
    public Builder setUrl(String url);
334
    public Builder setMethod(String method);
335
    public Builder setHeaders(Property[] headers);
336
    public Builder setConnectTimeoutMillis(int connectTimeoutMillis);
337
    public Builder setReadTimeoutMillis(int readTimeoutMillis);
338
    public HttpAppender build();
339
}
340
```
341

342
### Syslog Appender
343

344
Sends log events to syslog daemon.
345

346
```java { .api }
347
/**
348
 * Create SyslogAppender with builder pattern
349
 * @return SyslogAppender.Builder instance
350
 */
351
public static SyslogAppender.Builder newBuilder();
352

353
/**
354
 * SyslogAppender configuration builder
355
 */
356
public static final class Builder implements org.apache.logging.log4j.core.util.Builder<SyslogAppender> {
357
    public Builder setName(String name);
358
    public Builder setLayout(Layout<? extends Serializable> layout);
359
    public Builder setFilter(Filter filter);
360
    public Builder setHost(String host);
361
    public Builder setPort(int port);
362
    public Builder setProtocol(String protocol);
363
    public Builder setFacility(Facility facility);
364
    public SyslogAppender build();
365
}
366
```
367

368
## Triggering Policies
369

370
Policies that determine when rolling file appenders should roll over.
371

372
### Size Based Triggering Policy
373

374
```java { .api }
375
/**
376
 * Create size-based triggering policy
377
 * @param size Maximum file size (e.g., "10MB", "1GB")
378
 * @return SizeBasedTriggeringPolicy instance
379
 */
380
public static SizeBasedTriggeringPolicy createPolicy(String size);
381
```
382

383
### Time Based Triggering Policy
384

385
```java { .api }
386
/**
387
 * Create time-based triggering policy with builder
388
 * @return TimeBasedTriggeringPolicy.Builder instance
389
 */
390
public static TimeBasedTriggeringPolicy.Builder newBuilder();
391

392
public static final class Builder implements org.apache.logging.log4j.core.util.Builder<TimeBasedTriggeringPolicy> {
393
    public Builder withInterval(int interval);
394
    public Builder withModulate(boolean modulate);
395
    public Builder withMaxRandomDelay(int maxRandomDelay);
396
    public TimeBasedTriggeringPolicy build();
397
}
398
```
399

400
## Rollover Strategies
401

402
Strategies that control how files are rolled over and managed.
403

404
### Default Rollover Strategy
405

406
```java { .api }
407
/**
408
 * Create default rollover strategy with builder
409
 * @return DefaultRolloverStrategy.Builder instance
410
 */
411
public static DefaultRolloverStrategy.Builder newBuilder();
412

413
public static final class Builder implements org.apache.logging.log4j.core.util.Builder<DefaultRolloverStrategy> {
414
    public Builder withMax(String max);
415
    public Builder withMin(String min);
416
    public Builder withFileIndex(String fileIndex);
417
    public Builder withCompressionLevel(int compressionLevel);
418
    public DefaultRolloverStrategy build();
419
}
420
```