0
# Core Logging Interface
1

2
Essential logging functionality providing the main Logger interface, LogManager factory, and logging levels. This is the primary API that most applications use for logging operations.
3

4
## Capabilities
5

6
### LogManager Factory
7

8
Central factory for obtaining Logger instances and managing the logging system lifecycle.
9

10
```java { .api }
11
/**
12
 * Central factory for obtaining Logger instances and managing LoggerContexts
13
 */
14
public final class LogManager {
15
    /** Get logger for the calling class */
16
    public static Logger getLogger();
17
    
18
    /** Get logger for the specified class */
19
    public static Logger getLogger(Class<?> clazz);
20
    
21
    /** Get logger by name */
22
    public static Logger getLogger(String name);
23
    
24
    /** Get logger with custom message factory */
25
    public static Logger getLogger(Class<?> clazz, MessageFactory messageFactory);
26
    
27
    /** Get formatter logger for calling class (uses String.format) */
28
    public static Logger getFormatterLogger();
29
    
30
    /** Get formatter logger for specified class */
31
    public static Logger getFormatterLogger(Class<?> clazz);
32
    
33
    /** Get current LoggerContext */
34
    public static LoggerContext getContext();
35
    
36
    /** Get LoggerContext with control over context selection */
37
    public static LoggerContext getContext(boolean currentContext);
38
    
39
    /** Shutdown the logging system */
40
    public static void shutdown();
41
    
42
    /** Check if a logger with the given name exists */
43
    public static boolean exists(String name);
44
    
45
    /** Name of the root logger (empty string) */
46
    public static final String ROOT_LOGGER_NAME = "";
47
}
48
```
49

50
**Usage Examples:**
51

52
```java
53
// Most common usage - logger for current class
54
private static final Logger logger = LogManager.getLogger();
55

56
// Logger for specific class
57
private static final Logger logger = LogManager.getLogger(MyClass.class);
58

59
// Logger by name
60
private static final Logger logger = LogManager.getLogger("com.example.module");
61

62
// Formatter logger (uses String.format instead of {} placeholders)
63
private static final Logger formatter = LogManager.getFormatterLogger();
64
formatter.info("User %s has %d items", username, itemCount);
65

66
// Application shutdown
67
Runtime.getRuntime().addShutdownHook(new Thread(() -> {
68
    LogManager.shutdown();
69
}));
70
```
71

72
### Logger Interface
73

74
Main logging interface providing methods for all logging levels and core logging operations.
75

76
```java { .api }
77
/**
78
 * Central interface for logging operations
79
 */
80
public interface Logger {
81
    // Level-specific logging methods
82
    void trace(String message);
83
    void debug(String message);
84
    void info(String message);
85
    void warn(String message);
86
    void error(String message);
87
    void fatal(String message);
88
    
89
    // Parameterized logging (all levels support Object... params)
90
    void trace(String message, Object... params);
91
    void debug(String message, Object... params);
92
    void info(String message, Object... params);
93
    void warn(String message, Object... params);
94
    void error(String message, Object... params);
95
    void fatal(String message, Object... params);
96
    
97
    // Exception logging
98
    void trace(String message, Throwable throwable);
99
    void debug(String message, Throwable throwable);
100
    void info(String message, Throwable throwable);
101
    void warn(String message, Throwable throwable);
102
    void error(String message, Throwable throwable);
103
    void fatal(String message, Throwable throwable);
104
    
105
    // Generic logging
106
    void log(Level level, String message);
107
    void log(Level level, String message, Object... params);
108
    void log(Level level, String message, Throwable throwable);
109
    
110
    // Level checking
111
    boolean isTraceEnabled();
112
    boolean isDebugEnabled();
113
    boolean isInfoEnabled();
114
    boolean isWarnEnabled();
115
    boolean isErrorEnabled();
116
    boolean isFatalEnabled();
117
    boolean isEnabled(Level level);
118
    
119
    // Flow tracing
120
    void traceEntry();
121
    void traceEntry(String format, Object... params);
122
    <T> T traceExit(T result);
123
    void traceExit();
124
    
125
    // Exception flow
126
    <T extends Throwable> T catching(T throwable);
127
    <T extends Throwable> T throwing(T throwable);
128
    
129
    // Properties
130
    Level getLevel();
131
    String getName();
132
    MessageFactory getMessageFactory();
133
    FlowMessageFactory getFlowMessageFactory();
134
}
135
```
136

137
**Usage Examples:**
138

139
```java
140
private static final Logger logger = LogManager.getLogger();
141

142
public void demonstrateLogging() {
143
    // Basic logging
144
    logger.info("Application started");
145
    logger.warn("This is a warning message");
146
    
147
    // Parameterized logging (efficient - no string concatenation if disabled)
148
    String username = "alice";
149
    int attempts = 3;
150
    logger.info("User {} has {} login attempts", username, attempts);
151
    
152
    // Exception logging
153
    try {
154
        riskyOperation();
155
    } catch (Exception e) {
156
        logger.error("Failed to perform risky operation", e);
157
    }
158
    
159
    // Conditional logging (avoid expensive operations)
160
    if (logger.isDebugEnabled()) {
161
        logger.debug("Expensive debug info: {}", expensiveCalculation());
162
    }
163
    
164
    // Generic level logging
165
    Level dynamicLevel = getDynamicLevel();
166
    logger.log(dynamicLevel, "Dynamic level message");
167
    
168
    // Flow tracing
169
    logger.traceEntry();
170
    try {
171
        String result = processData();
172
        return logger.traceExit(result);
173
    } catch (Exception e) {
174
        throw logger.throwing(e);
175
    }
176
}
177
```
178

179
### Logging Levels
180

181
Hierarchy of logging levels with comparison capabilities for filtering and configuration.
182

183
```java { .api }
184
/**
185
 * Logging levels with hierarchy and comparison capabilities
186
 */
187
public final class Level implements Comparable<Level>, Serializable {
188
    // Standard levels (in order of increasing verbosity)
189
    public static final Level OFF;    // No logging
190
    public static final Level FATAL;  // Fatal errors
191
    public static final Level ERROR;  // Error conditions
192
    public static final Level WARN;   // Warning conditions
193
    public static final Level INFO;   // Informational messages
194
    public static final Level DEBUG;  // Debug messages
195
    public static final Level TRACE;  // Trace messages
196
    public static final Level ALL;    // All messages
197
    
198
    /** Get the numeric level value */
199
    public int intLevel();
200
    
201
    /** Check if this level is less specific than the given level */
202
    public boolean isLessSpecificThan(Level level);
203
    
204
    /** Check if this level is more specific than the given level */
205
    public boolean isMoreSpecificThan(Level level);
206
    
207
    /** Check if this level is within the given range */
208
    public boolean isInRange(Level minLevel, Level maxLevel);
209
    
210
    /** Create or get a custom level */
211
    public static Level forName(String name, int intValue);
212
    
213
    /** Get level by name (case-insensitive) */
214
    public static Level valueOf(String name);
215
    
216
    /** Convert string to level with fallback */
217
    public static Level toLevel(String level);
218
    public static Level toLevel(String level, Level defaultLevel);
219
    
220
    @Override
221
    public int compareTo(Level other);
222
}
223
```
224

225
**Usage Examples:**
226

227
```java
228
// Level comparison
229
Level currentLevel = logger.getLevel();
230
if (currentLevel.isMoreSpecificThan(Level.INFO)) {
231
    // DEBUG or TRACE logging is enabled
232
    logger.debug("Detailed debugging information");
233
}
234

235
// Custom levels
236
Level NOTICE = Level.forName("NOTICE", 350); // Between INFO(400) and WARN(300)
237
logger.log(NOTICE, "This is a notice");
238

239
// String to level conversion
240
String configLevel = System.getProperty("log.level", "INFO");
241
Level level = Level.toLevel(configLevel, Level.INFO);
242

243
// Level range checking
244
if (Level.DEBUG.isInRange(Level.TRACE, Level.INFO)) {
245
    // DEBUG is between TRACE and INFO (inclusive)
246
}
247

248
// Sorting levels
249
List<Level> levels = Arrays.asList(Level.ERROR, Level.DEBUG, Level.INFO);
250
Collections.sort(levels); // Results in: DEBUG, INFO, ERROR
251
```
252

253
### Root Logger
254

255
Special logger instance representing the root of the logger hierarchy.
256

257
```java { .api }
258
// Access root logger
259
Logger rootLogger = LogManager.getLogger(LogManager.ROOT_LOGGER_NAME);
260
Logger rootLogger2 = LogManager.getLogger(""); // Same as above
261

262
// Root logger name constant
263
public static final String ROOT_LOGGER_NAME = "";
264
```
265

266
**Usage Examples:**
267

268
```java
269
// Configure root logger level programmatically (implementation-dependent)
270
Logger rootLogger = LogManager.getLogger(LogManager.ROOT_LOGGER_NAME);
271

272
// All loggers inherit from root logger's configuration
273
Logger specificLogger = LogManager.getLogger("com.example.MyClass");
274
// specificLogger will inherit root logger's level if not explicitly configured
275
```