0
# Logback Core
1

2
Logback Core is the foundational module of the Logback logging framework, providing core infrastructure and basic components for logging operations in Java applications. It serves as the base layer for all other Logback modules, implementing essential functionality including appenders (for writing log events to various destinations), encoders and layouts (for formatting log messages), filters (for selective log processing), and the core event processing pipeline.
3

4
## Package Information
5

6
- **Package Name**: ch.qos.logback:logback-core
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Version**: 1.5.18
10
- **License**: EPL-1.0 OR LGPL-2.1
11
- **Installation**: 
12
  ```xml
13
  <dependency>
14
    <groupId>ch.qos.logback</groupId>
15
    <artifactId>logback-core</artifactId>
16
    <version>1.5.18</version>
17
  </dependency>
18
  ```
19

20
## Core Imports
21

22
```java
23
import ch.qos.logback.core.*;
24
import ch.qos.logback.core.spi.*;
25
```
26

27
Common specific imports:
28

29
```java
30
import ch.qos.logback.core.AppenderBase;
31
import ch.qos.logback.core.Context;
32
import ch.qos.logback.core.FileAppender;
33
import ch.qos.logback.core.ConsoleAppender;
34
import ch.qos.logback.core.encoder.LayoutWrappingEncoder;
35
import ch.qos.logback.core.rolling.RollingFileAppender;
36
import ch.qos.logback.core.rolling.TimeBasedRollingPolicy;
37
import ch.qos.logback.core.spi.LifeCycle;
38
import ch.qos.logback.core.spi.ContextAware;
39
```
40

41
## Basic Usage
42

43
```java
44
import ch.qos.logback.core.*;
45
import ch.qos.logback.core.encoder.*;
46
import ch.qos.logback.core.rolling.*;
47

48
// Create a context (usually provided by logback-classic)
49
Context context = new ContextBase();
50

51
// Create a console appender
52
ConsoleAppender<Object> consoleAppender = new ConsoleAppender<>();
53
consoleAppender.setContext(context);
54
consoleAppender.setTarget("System.out");
55

56
// Create and configure an encoder
57
LayoutWrappingEncoder<Object> encoder = new LayoutWrappingEncoder<>();
58
encoder.setContext(context);
59
// encoder.setLayout(someLayout); // Layout would be set here
60
encoder.start();
61

62
consoleAppender.setEncoder(encoder);
63
consoleAppender.start();
64

65
// Create a file appender with rolling
66
RollingFileAppender<Object> fileAppender = new RollingFileAppender<>();
67
fileAppender.setContext(context);
68
fileAppender.setFile("application.log");
69

70
// Configure rolling policy
71
TimeBasedRollingPolicy<Object> rollingPolicy = new TimeBasedRollingPolicy<>();
72
rollingPolicy.setContext(context);
73
rollingPolicy.setParent(fileAppender);
74
rollingPolicy.setFileNamePattern("application.%d{yyyy-MM-dd}.log");
75
rollingPolicy.setMaxHistory(30);
76
rollingPolicy.start();
77

78
fileAppender.setRollingPolicy(rollingPolicy);
79
fileAppender.setTriggeringPolicy(rollingPolicy);
80
fileAppender.setEncoder(encoder);
81
fileAppender.start();
82

83
// Use the appenders (typically done by logging framework)
84
// consoleAppender.doAppend(someEvent);
85
// fileAppender.doAppend(someEvent);
86
```
87

88
## Architecture
89

90
Logback Core is built around several key architectural components:
91

92
- **Context**: Central anchorage point providing shared services, configuration, and lifecycle management
93
- **Appenders**: Write log events to destinations (console, files, network, databases)
94
- **Encoders/Layouts**: Transform log events into formatted output (text, JSON, XML)
95
- **Filters**: Selective processing with accept/deny/neutral decisions on log events
96
- **SPI Framework**: Service Provider Interfaces enabling extensibility and custom implementations
97
- **Configuration Engine**: XML-based configuration processing through the Joran framework
98
- **Pattern Processing**: Flexible pattern-based formatting with conversion chains
99
- **Lifecycle Management**: Consistent start/stop semantics across all components
100

101
The framework follows a Template Method pattern where base classes provide structure and subclasses implement specific behavior, enabling extensive customization while maintaining consistent interfaces.
102

103
## Capabilities
104

105
### Core Appenders
106

107
Foundation appender classes and interfaces for writing log events to various destinations, with built-in support for console, file, and asynchronous output.
108

109
```java { .api }
110
public interface Appender<E> extends LifeCycle, ContextAware, FilterAttachable<E> {
111
    String getName();
112
    void doAppend(E event) throws LogbackException;
113
    void setName(String name);
114
}
115

116
public abstract class AppenderBase<E> extends ContextAwareBase 
117
    implements Appender<E> {
118
    public synchronized void doAppend(E eventObject);
119
    protected abstract void append(E eventObject);
120
}
121

122
public class ConsoleAppender<E> extends OutputStreamAppender<E> {
123
    public void setTarget(String value);
124
    public String getTarget();
125
}
126

127
public class FileAppender<E> extends OutputStreamAppender<E> {
128
    public void setFile(String file);
129
    public String getFile();
130
    public void setAppend(boolean append);
131
    public void setPrudent(boolean prudent);
132
}
133
```
134

135
[Appenders](./appenders.md)
136

137
### Encoders and Layouts
138

139
Event encoding and transformation system for converting log events into formatted byte arrays or strings, supporting various output formats and character encodings.
140

141
```java { .api }
142
public interface Encoder<E> extends ContextAware, LifeCycle {
143
    byte[] headerBytes();
144
    byte[] encode(E event);
145
    byte[] footerBytes();
146
}
147

148
public interface Layout<E> extends ContextAware, LifeCycle {
149
    String doLayout(E event);
150
    String getFileHeader();
151
    String getFileFooter();
152
    String getContentType();
153
}
154

155
public class LayoutWrappingEncoder<E> extends EncoderBase<E> {
156
    public void setLayout(Layout<E> layout);
157
    public Layout<E> getLayout();
158
    public void setCharset(Charset charset);
159
}
160
```
161

162
[Encoders and Layouts](./encoders-layouts.md)
163

164
### Event Filtering
165

166
Comprehensive filtering system for selective log processing, supporting filter chains, boolean expression evaluators, and custom filter implementations.
167

168
```java { .api }
169
public abstract class Filter<E> extends ContextAwareBase implements LifeCycle {
170
    public abstract FilterReply decide(E event);
171
    public void setName(String name);
172
    public String getName();
173
}
174

175
public enum FilterReply {
176
    DENY, NEUTRAL, ACCEPT
177
}
178

179
public interface EventEvaluator<E> extends ContextAware, LifeCycle {
180
    boolean evaluate(E event);
181
    String getName();
182
    void setName(String name);
183
}
184

185
public interface FilterAttachable<E> {
186
    void addFilter(Filter<E> newFilter);
187
    void clearAllFilters();
188
    FilterReply getFilterChainDecision(E event);
189
}
190
```
191

192
[Filters and Evaluators](./filters-evaluators.md)
193

194
### File Rolling Policies
195

196
Advanced file management with time-based and size-based rolling, compression support, and cleanup policies for log file rotation and archival.
197

198
```java { .api }
199
public interface RollingPolicy extends LifeCycle {
200
    void rollover() throws RolloverFailure;
201
    String getActiveFileName();
202
    CompressionMode getCompressionMode();
203
    void setParent(FileAppender<?> appender);
204
}
205

206
public interface TriggeringPolicy<E> extends LifeCycle {
207
    boolean isTriggeringEvent(File activeFile, E event);
208
}
209

210
public class TimeBasedRollingPolicy<E> extends RollingPolicyBase 
211
    implements TriggeringPolicy<E> {
212
    public void setMaxFileSize(FileSize maxFileSize);
213
    public void setCleanHistoryOnStart(boolean cleanHistoryOnStart);
214
}
215

216
public class RollingFileAppender<E> extends FileAppender<E> {
217
    public void setRollingPolicy(RollingPolicy policy);
218
    public void setTriggeringPolicy(TriggeringPolicy<E> policy);
219
}
220
```
221

222
[Rolling Policies](./rolling-policies.md)
223

224
### Network Logging
225

226
Network-based logging capabilities including TCP sockets, syslog protocol, email notifications, and SSL/TLS security for remote log transmission.
227

228
```java { .api }
229
public class SocketAppender extends AppenderBase<ILoggingEvent> {
230
    public void setRemoteHost(String host);
231
    public void setPort(int port);
232
    public void setReconnectionDelay(Duration delay);
233
    public void setQueueSize(int queueSize);
234
}
235

236
public class SyslogAppender extends AppenderBase<ILoggingEvent> {
237
    public void setSyslogHost(String syslogHost);
238
    public void setFacility(String facilityStr);
239
    public void setSuffixPattern(String suffixPattern);
240
}
241

242
public class SMTPAppender extends AppenderBase<ILoggingEvent> {
243
    public void setTo(String to);
244
    public void setSMTPHost(String smtpHost);
245
    public void setBufferSize(int bufferSize);
246
}
247
```
248

249
[Network Logging](./network-logging.md)
250

251
### Configuration Framework
252

253
XML-based configuration processing through the Joran framework, supporting property substitution, conditional configuration, and extensible action handlers.
254

255
```java { .api }
256
public abstract class GenericXMLConfigurator extends ContextAwareBase {
257
    public void doConfigure(URL url) throws JoranException;
258
    public void doConfigure(File file) throws JoranException;
259
    public void doConfigure(InputStream inputStream) throws JoranException;
260
}
261

262
public class JoranConfigurator extends GenericXMLConfigurator {
263
    public void configure(Context context, URL url) throws JoranException;
264
    public List<SaxEvent> recordEvents(InputStream inputStream);
265
}
266

267
public interface Context extends PropertyContainer {
268
    StatusManager getStatusManager();
269
    void putObject(String key, Object value);
270
    Object getObject(String key);
271
    ExecutorService getExecutorService();
272
    ScheduledExecutorService getScheduledExecutorService();
273
}
274
```
275

276
[Configuration](./configuration.md)
277

278
### Model Framework
279

280
Configuration model system providing hierarchical representation of logback components with processing, state tracking, and integration with the Joran configuration framework.
281

282
```java { .api }
283
public class Model implements Serializable {
284
    public int getLineNumber();
285
    public Model getParent();
286
    public void addSubModel(Model child);
287
    public List<Model> getSubModels();
288
    public boolean isProcessed();
289
    public String getTag();
290
    public String getBodyText();
291
}
292

293
public class ComponentModel extends Model {
294
    public String getClassName();
295
    public Class<?> getClazz();
296
}
297

298
public class NamedComponentModel extends ComponentModel implements INamedModel {
299
    public String getName();
300
    public void setName(String name);
301
}
302
```
303

304
[Model Framework](./model-framework.md)
305

306
### Pattern Processing
307

308
Flexible pattern-based formatting system with conversion chains, color support, and extensible converter framework for custom log formatting.
309

310
```java { .api }
311
public abstract class PatternLayoutBase<E> extends LayoutBase<E> {
312
    public void setPattern(String pattern);
313
    public String getPattern();
314
}
315

316
public abstract class Converter<E> implements ContextAware {
317
    public abstract void write(StringBuilder buf, E event);
318
    public void setNext(Converter<E> next);
319
    public Converter<E> getNext();
320
}
321

322
public abstract class FormattingConverter<E> extends Converter<E> {
323
    public abstract String convert(E event);
324
    public void setFormattingInfo(FormatInfo fi);
325
}
326
```
327

328
[Pattern Processing](./patterns.md)
329

330
### Utilities and Helpers
331

332
Comprehensive utility classes for file operations, date formatting, duration handling, size parsing, thread management, and testing support.
333

334
```java { .api }
335
public class FileSize {
336
    public FileSize(long size);
337
    public void setSize(String str);
338
    public long getSize();
339
    public String toString();
340
    public static long valueOf(String s);
341
}
342

343
public class Duration {
344
    public long getMilliseconds();
345
    public void setMilliseconds(long milliseconds);
346
    public String toString();
347
    public static Duration valueOf(String s);
348
}
349

350
public class OptionHelper {
351
    public static String substVars(String val, PropertyContainer pc);
352
    public static Object instantiateByClassName(String className, 
353
        Class<?> superClass, Context context);
354
}
355
```
356

357
[Utilities](./utilities.md)
358

359
## Core Constants
360

361
```java { .api }
362
public class CoreConstants {
363
    // Context and Configuration Keys
364
    public static final String DEFAULT_CONTEXT_NAME = "default";
365
    public static final String STATUS_LISTENER_CLASS_KEY = "logback.statusListenerClass";
366
    public static final String DISABLE_SERVLET_CONTAINER_INITIALIZER_KEY = "logbackDisableServletContainerInitializer";
367
    public static final String PATTERN_RULE_REGISTRY = "PATTERN_RULE_REGISTRY";
368
    public static final String EVALUATOR_MAP = "EVALUATOR_MAP";
369
    public static final String HOSTNAME_KEY = "HOSTNAME";
370
    public static final String CONTEXT_NAME_KEY = "CONTEXT_NAME";
371
    
372
    // Thread Pool Configuration
373
    public static final int CORE_POOL_SIZE = 4;
374
    public static final int SCHEDULED_EXECUTOR_POOL_SIZE = 4;
375
    public static final int MAX_POOL_SIZE = 32; // @deprecated
376
    
377
    // Size and Count Limits
378
    public static final int TABLE_ROW_LIMIT = 10000;
379
    public static final int MAX_ERROR_COUNT = 4;
380
    public static final int OOS_RESET_FREQUENCY = 70;
381
    public static final int SECONDS_TO_WAIT_FOR_COMPRESSION_JOBS = 30;
382
    public static final long UNBOUNDED_TOTAL_SIZE_CAP = 0;
383
    public static final int UNBOUNDED_HISTORY = 0;
384
    
385
    // Character Constants
386
    public static final char PERCENT_CHAR = '%';
387
    public static final char ESCAPE_CHAR = '\\';
388
    public static final char CURLY_LEFT = '{';
389
    public static final char CURLY_RIGHT = '}';
390
    public static final char COLON_CHAR = ':';
391
    public static final char COMMA_CHAR = ',';
392
    public static final char DOT = '.';
393
    public static final char DOLLAR = '$';
394
    
395
    // String Constants
396
    public static final String LINE_SEPARATOR = System.getProperty("line.separator");
397
    public static final String EMPTY_STRING = "";
398
    public static final String NULL_STR = "null";
399
    public static final String NA = "?";
400
    public static final String SYSOUT = "SYSOUT";
401
    public static final String STDOUT = "STDOUT";
402
    
403
    // Time Constants (in milliseconds)
404
    public static final long MILLIS_IN_ONE_SECOND = 1000;
405
    public static final long MILLIS_IN_ONE_MINUTE = MILLIS_IN_ONE_SECOND * 60;
406
    public static final long MILLIS_IN_ONE_HOUR = MILLIS_IN_ONE_MINUTE * 60;
407
    public static final long MILLIS_IN_ONE_DAY = MILLIS_IN_ONE_HOUR * 24;
408
    public static final long MILLIS_IN_ONE_WEEK = MILLIS_IN_ONE_DAY * 7;
409
    
410
    // Date and Time Patterns
411
    public static final String ISO8601_STR = "ISO8601";
412
    public static final String ISO8601_PATTERN = "yyyy-MM-dd HH:mm:ss,SSS";
413
    public static final String STRICT_ISO8601_PATTERN = "yyyy-MM-dd'T'HH:mm:ss,SSS";
414
    public static final String DAILY_DATE_PATTERN = "yyyy-MM-dd";
415
    public static final String CLF_DATE_PATTERN = "dd/MMM/yyyy:HH:mm:ss Z";
416
    public static final String FILE_TIMESTAMP_PATTERN = "yyyy-MM-dd'T'HHmm";
417
    
418
    // URL Patterns
419
    public static final String CODES_URL = "https://logback.qos.ch/codes.html";
420
    public static final String MANUAL_URL_PREFIX = "https://logback.qos.ch/manual/";
421
    
422
    // Charset and Arrays
423
    public static final Charset UTF_8_CHARSET = StandardCharsets.UTF_8;
424
    public static final String[] EMPTY_STRING_ARRAY = new String[] {};
425
    public static final Class<?>[] EMPTY_CLASS_ARRAY = new Class[] {};
426
    
427
    // File Extensions
428
    public static final String MODEL_CONFIG_FILE_EXTENSION = ".scmo";
429
    public static final String PROPERTIES_FILE_EXTENSION = ".properties";
430
    
431
    // JNDI Constants
432
    public static final String JNDI_JAVA_NAMESPACE = "java:";
433
    public static final String JNDI_COMP_PREFIX = "java:comp/env";
434
}
435
```
436

437
## Core Exceptions
438

439
```java { .api }
440
public class LogbackException extends RuntimeException {
441
    public LogbackException(String msg);
442
    public LogbackException(String msg, Throwable cause);
443
}
444

445
public class EvaluationException extends Exception {
446
    public EvaluationException(String msg);
447
    public EvaluationException(String msg, Throwable cause);
448
}
449
```
450

451
## Service Provider Interfaces
452

453
```java { .api }
454
public interface LifeCycle {
455
    void start();
456
    void stop();
457
    boolean isStarted();
458
}
459

460
public interface ContextAware {
461
    void setContext(Context context);
462
    Context getContext();
463
    void addStatus(Status status);
464
    void addInfo(String msg);
465
    void addInfo(String msg, Throwable ex);
466
    void addWarn(String msg);
467
    void addWarn(String msg, Throwable ex);
468
    void addError(String msg);
469
    void addError(String msg, Throwable ex);
470
}
471

472
public interface PropertyContainer {
473
    String getProperty(String key);
474
    void putProperty(String key, String value);
475
    Map<String, String> getCopyOfPropertyMap();
476
}
477
```