0
# Core Logging
1

2
Essential logging functionality including the Logger interface, logging contexts, level management, and the foundational components of the Logback Classic logging system.
3

4
## Capabilities
5

6
### Logger Interface
7

8
The main logging facade implementing the SLF4J Logger interface with Logback-specific extensions.
9

10
```java { .api }
11
/**
12
 * Main logger interface implementing SLF4J Logger with Logback extensions
13
 */
14
public final class Logger implements org.slf4j.Logger, LocationAwareLogger, AppenderAttachable<ILoggingEvent> {
15
    // Constants
16
    public static final String FQCN = "ch.qos.logback.classic.Logger";
17
    // ROOT_LOGGER_NAME is inherited from org.slf4j.Logger interface
18
    
19
    // Basic logging methods
20
    public void trace(String msg);
21
    public void debug(String msg);
22
    public void info(String msg);
23
    public void warn(String msg);
24
    public void error(String msg);
25
    
26
    // Parameterized logging
27
    public void trace(String format, Object arg);
28
    public void trace(String format, Object arg1, Object arg2);
29
    public void trace(String format, Object... arguments);
30
    
31
    public void debug(String format, Object arg);
32
    public void debug(String format, Object arg1, Object arg2);
33
    public void debug(String format, Object... arguments);
34
    
35
    public void info(String format, Object arg);
36
    public void info(String format, Object arg1, Object arg2);
37
    public void info(String format, Object... arguments);
38
    
39
    public void warn(String format, Object arg);
40
    public void warn(String format, Object arg1, Object arg2);
41
    public void warn(String format, Object... arguments);
42
    
43
    public void error(String format, Object arg);
44
    public void error(String format, Object arg1, Object arg2);
45
    public void error(String format, Object... arguments);
46
    
47
    // Exception logging
48
    public void trace(String msg, Throwable t);
49
    public void debug(String msg, Throwable t);
50
    public void info(String msg, Throwable t);
51
    public void warn(String msg, Throwable t);
52
    public void error(String msg, Throwable t);
53
    
54
    // Marker-based logging
55
    public void trace(Marker marker, String msg);
56
    public void debug(Marker marker, String msg);
57
    public void info(Marker marker, String msg);
58
    public void warn(Marker marker, String msg);
59
    public void error(Marker marker, String msg);
60
    
61
    // Level checking
62
    public boolean isTraceEnabled();
63
    public boolean isDebugEnabled();
64
    public boolean isInfoEnabled();
65
    public boolean isWarnEnabled();
66
    public boolean isErrorEnabled();
67
    
68
    // Logback-specific methods
69
    public Level getLevel();
70
    public void setLevel(Level level);
71
    public Level getEffectiveLevel();
72
    public boolean isEnabledFor(Level level);
73
    
74
    // Appender management
75
    public void addAppender(Appender<ILoggingEvent> newAppender);
76
    public boolean detachAppender(Appender<ILoggingEvent> appender);
77
    public boolean detachAppender(String name);
78
    public void detachAndStopAllAppenders();
79
    
80
    // Hierarchy management
81
    public LoggerContext getLoggerContext();
82
    public String getName();
83
    public Logger getParent();
84
    public void setParent(Logger parent);
85
    public boolean getAdditivity();
86
    public void setAdditivity(boolean additivity);
87
}
88
```
89

90
**Usage Examples:**
91

92
```java
93
import org.slf4j.Logger;
94
import org.slf4j.LoggerFactory;
95

96
public class UserService {
97
    private static final Logger logger = LoggerFactory.getLogger(UserService.class);
98
    
99
    public User createUser(String username, String email) {
100
        logger.info("Creating user: username={}, email={}", username, email);
101
        
102
        try {
103
            User user = new User(username, email);
104
            logger.debug("User object created: {}", user);
105
            return user;
106
        } catch (Exception e) {
107
            logger.error("Failed to create user: username={}", username, e);
108
            throw e;
109
        }
110
    }
111
}
112
```
113

114
### LoggerContext
115

116
Central registry and factory for Logger instances, managing the logger hierarchy and system-wide configuration.
117

118
```java { .api }
119
/**
120
 * Central logger context managing the logger hierarchy and system configuration
121
 */
122
public class LoggerContext extends ContextBase implements ILoggerFactory, LifeCycle {
123
    // Constants
124
    public static final boolean DEFAULT_PACKAGING_DATA = false;
125
    
126
    // Logger management
127
    public Logger getLogger(String name);
128
    public Logger getLogger(Class<?> clazz);
129
    public Logger exists(String name);
130
    public List<Logger> getLoggerList();
131
    
132
    // Lifecycle management
133
    public void start();
134
    public void stop();
135
    public boolean isStarted();
136
    
137
    // Configuration
138
    public void reset();
139
    public void setPackagingDataEnabled(boolean packagingDataEnabled);
140
    public boolean isPackagingDataEnabled();
141
    public void setMaxCallerDataDepth(int maxCallerDataDepth);
142
    public int getMaxCallerDataDepth();
143
    
144
    // Turbo filters
145
    public void addTurboFilter(TurboFilter newFilter);
146
    public void resetTurboFilterList();
147
    public List<TurboFilter> getTurboFilterList();
148
    
149
    // Context properties
150
    public void putProperty(String key, String val);
151
    public String getProperty(String key);
152
    public Map<String, String> getCopyOfPropertyMap();
153
    
154
    // Listeners
155
    public void addListener(LoggerContextListener listener);
156
    public void removeListener(LoggerContextListener listener);
157
    
158
    // Status and metadata
159
    public LoggerContextVO getLoggerContextRemoteView();
160
    public String getName();
161
    public void setName(String name);
162
    public long getBirthTime();
163
    public Object getConfigurationLock();
164
}
165
```
166

167
**Usage Examples:**
168

169
```java
170
import ch.qos.logback.classic.LoggerContext;
171
import org.slf4j.LoggerFactory;
172

173
// Get the logger context
174
LoggerContext context = (LoggerContext) LoggerFactory.getILoggerFactory();
175

176
// Configure context properties
177
context.putProperty("app.name", "MyApplication");
178
context.putProperty("app.version", "1.0.0");
179

180
// Reset configuration
181
context.reset();
182

183
// Enable packaging data for stack traces
184
context.setPackagingDataEnabled(true);
185
```
186

187
### Level
188

189
Defines the hierarchy of logging levels with integer values for comparison and filtering.
190

191
```java { .api }
192
/**
193
 * Defines logging levels with integer values for efficient comparison
194
 */
195
public final class Level implements Serializable {
196
    // Level integer constants
197
    public static final int OFF_INT = Integer.MAX_VALUE;
198
    public static final int ERROR_INT = 40000;
199
    public static final int WARN_INT = 30000;
200
    public static final int INFO_INT = 20000;
201
    public static final int DEBUG_INT = 10000;
202
    public static final int TRACE_INT = 5000;
203
    public static final int ALL_INT = Integer.MIN_VALUE;
204
    
205
    // Integer wrapper constants
206
    public static final Integer OFF_INTEGER = OFF_INT;
207
    public static final Integer ERROR_INTEGER = ERROR_INT;
208
    public static final Integer WARN_INTEGER = WARN_INT;
209
    public static final Integer INFO_INTEGER = INFO_INT;
210
    public static final Integer DEBUG_INTEGER = DEBUG_INT;
211
    public static final Integer TRACE_INTEGER = TRACE_INT;
212
    public static final Integer ALL_INTEGER = ALL_INT;
213
    
214
    // Level instances
215
    public static final Level OFF = new Level(OFF_INT, "OFF");
216
    public static final Level ERROR = new Level(ERROR_INT, "ERROR");
217
    public static final Level WARN = new Level(WARN_INT, "WARN");
218
    public static final Level INFO = new Level(INFO_INT, "INFO");
219
    public static final Level DEBUG = new Level(DEBUG_INT, "DEBUG");
220
    public static final Level TRACE = new Level(TRACE_INT, "TRACE");
221
    /** @deprecated with no replacement - use TRACE level instead */
222
    public static final Level ALL = new Level(ALL_INT, "ALL");
223
    
224
    // Level operations
225
    public String toString();
226
    public int toInt();
227
    public boolean isGreaterOrEqual(Level r);
228
    public static Level toLevel(String sArg);
229
    public static Level toLevel(int val);
230
    public static Level valueOf(String sArg);
231
}
232
```
233

234
**Usage Examples:**
235

236
```java
237
import ch.qos.logback.classic.Logger;
238
import ch.qos.logback.classic.Level;
239

240
// Set logger level programmatically
241
Logger logger = (Logger) LoggerFactory.getLogger("com.example");
242
logger.setLevel(Level.DEBUG);
243

244
// Check effective level
245
Level effectiveLevel = logger.getEffectiveLevel();
246
System.out.println("Effective level: " + effectiveLevel);
247

248
// Level comparison
249
if (Level.INFO.isGreaterOrEqual(Level.DEBUG)) {
250
    System.out.println("INFO is greater than or equal to DEBUG");
251
}
252
```
253

254
### Logging Events
255

256
Core interfaces and classes representing individual logging events.
257

258
```java { .api }
259
/**
260
 * Central interface representing a logging event
261
 */
262
public interface ILoggingEvent extends DeferredProcessingAware {
263
    String getThreadName();
264
    Level getLevel();
265
    String getMessage();
266
    Object[] getArgumentArray();
267
    String getFormattedMessage();
268
    String getLoggerName();
269
    LoggerContextVO getLoggerContextVO();
270
    IThrowableProxy getThrowableProxy();
271
    StackTraceElement[] getCallerData();
272
    boolean hasCallerData();
273
    /** @deprecated Replaced by getMarkerList() */
274
    Marker getMarker();
275
    List<Marker> getMarkerList();
276
    Map<String, String> getMDCPropertyMap();
277
    /** @deprecated Replaced by getMDCPropertyMap() */
278
    Map<String, String> getMdc();
279
    long getTimeStamp();
280
    int getNanoseconds();
281
    long getSequenceNumber();
282
    List<KeyValuePair> getKeyValuePairs();
283
    Instant getInstant();
284
    void prepareForDeferredProcessing();
285
}
286

287
/**
288
 * Default implementation of ILoggingEvent
289
 */
290
public class LoggingEvent implements ILoggingEvent {
291
    // Constructors
292
    public LoggingEvent();
293
    public LoggingEvent(String fqcn, Logger logger, Level level, String message, Throwable throwable, Object[] argArray);
294
    
295
    // All ILoggingEvent methods implemented
296
    // Plus additional utility methods for event creation and manipulation
297
}
298

299
/**
300
 * Interface for exception information in logging events
301
 */
302
public interface IThrowableProxy {
303
    String getMessage();
304
    String getClassName();
305
    StackTraceElementProxy[] getStackTraceElementProxyArray();
306
    int getCommonFrames();
307
    IThrowableProxy getCause();
308
    IThrowableProxy[] getSuppressed();
309
    String getCycledCauseTrace();
310
    boolean isCyclic();
311
}
312
```
313

314
## Constants and Utilities
315

316
```java { .api }
317
/**
318
 * Constants used throughout Logback Classic
319
 */
320
public class ClassicConstants {
321
    // Configuration properties
322
    public static final String LOGBACK_CONTEXT_SELECTOR = "logback.ContextSelector";
323
    public static final String CONFIG_FILE_PROPERTY = "logback.configurationFile";
324
    public static final String MODEL_CONFIG_FILE_PROPERTY = "logback.scmoFile";
325
    
326
    // Default configuration files
327
    public static final String AUTOCONFIG_FILE = "logback.xml";
328
    public static final String TEST_AUTOCONFIG_FILE = "logback-test.xml";
329
    
330
    // System properties
331
    public static final int DEFAULT_MAX_CALLEDER_DATA_DEPTH = 8;
332
    public static final String USER_MDC_KEY = "user";
333
    
334
    // Request-related MDC keys
335
    public static final String REQUEST_REMOTE_HOST_MDC_KEY = "req.remoteHost";
336
    public static final String REQUEST_USER_AGENT_MDC_KEY = "req.userAgent";
337
    public static final String REQUEST_REQUEST_URI = "req.requestURI";
338
    public static final String REQUEST_QUERY_STRING = "req.queryString";
339
    public static final String REQUEST_REQUEST_URL = "req.requestURL";
340
    public static final String REQUEST_METHOD = "req.method";
341
    public static final String REQUEST_X_FORWARDED_FOR = "req.xForwardedFor";
342
}
343
```