0
# Apache Log4j API
1

2
Apache Log4j API is the core logging interface for the Log4j project, providing a comprehensive and flexible logging framework for Java applications. It serves as the foundational API that libraries and applications use for logging operations, featuring a clean interface that supports various logging levels, parameterized messages for performance optimization, and marker-based filtering capabilities.
3

4
## Package Information
5

6
- **Package Name**: org.apache.logging.log4j:log4j-api
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
      <groupId>org.apache.logging.log4j</groupId>
13
      <artifactId>log4j-api</artifactId>
14
      <version>2.25.1</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import org.apache.logging.log4j.LogManager;
22
import org.apache.logging.log4j.Logger;
23
```
24

25
Common additional imports:
26

27
```java
28
import org.apache.logging.log4j.Level;
29
import org.apache.logging.log4j.Marker;
30
import org.apache.logging.log4j.MarkerManager;
31
import org.apache.logging.log4j.ThreadContext;
32
```
33

34
## Basic Usage
35

36
```java
37
import org.apache.logging.log4j.LogManager;
38
import org.apache.logging.log4j.Logger;
39

40
public class MyApplication {
41
    private static final Logger logger = LogManager.getLogger(MyApplication.class);
42
    
43
    public void doSomething() {
44
        logger.info("Application started");
45
        
46
        try {
47
            // Application logic
48
            logger.debug("Processing user data");
49
            processUserData("user123");
50
            logger.info("User data processed successfully");
51
        } catch (Exception e) {
52
            logger.error("Error processing user data", e);
53
        }
54
    }
55
    
56
    private void processUserData(String userId) {
57
        // Parameterized logging for performance
58
        logger.info("Processing data for user: {}", userId);
59
        
60
        // Thread context for request tracking
61
        ThreadContext.put("userId", userId);
62
        logger.debug("Added user ID to thread context");
63
        ThreadContext.clear();
64
    }
65
}
66
```
67

68
## Architecture
69

70
Log4j API is built around several key components:
71

72
- **LogManager**: Central factory for obtaining Logger instances, serving as the primary entry point
73
- **Logger**: Main logging interface providing methods for all logging levels and advanced features
74
- **Level**: Enumeration of logging levels (TRACE, DEBUG, INFO, WARN, ERROR, FATAL) with comparison capabilities
75
- **Message System**: Flexible message creation with multiple formatting options and lazy evaluation
76
- **ThreadContext**: Per-thread context management (NDC/MDC) for request tracking and correlation
77
- **Service Provider Interface**: Extensible design allowing custom logger implementations and contexts
78

79
## Capabilities
80

81
### Core Logging Interface
82

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

85
```java { .api }
86
public final class LogManager {
87
    public static Logger getLogger();
88
    public static Logger getLogger(Class<?> clazz);
89
    public static Logger getLogger(String name);
90
    public static LoggerContext getContext();
91
    public static void shutdown();
92
}
93

94
public interface Logger {
95
    void trace(String message);
96
    void debug(String message);
97
    void info(String message);
98
    void warn(String message);
99
    void error(String message);
100
    void fatal(String message);
101
    void log(Level level, String message);
102
    boolean isEnabled(Level level);
103
    String getName();
104
}
105

106
public final class Level implements Comparable<Level> {
107
    public static final Level OFF;
108
    public static final Level FATAL;
109
    public static final Level ERROR;
110
    public static final Level WARN;
111
    public static final Level INFO;
112
    public static final Level DEBUG;
113
    public static final Level TRACE;
114
    public static final Level ALL;
115
    
116
    public int intLevel();
117
    public boolean isMoreSpecificThan(Level level);
118
    public static Level valueOf(String name);
119
}
120
```
121

122
[Core Logging](./core-logging.md)
123

124
### Parameterized Logging & Performance
125

126
High-performance logging features including parameterized messages with {} placeholders, supplier-based lazy evaluation, and fluent LogBuilder API for complex log events.
127

128
```java { .api }
129
public interface Logger {
130
    void info(String message, Object... params);
131
    void error(String message, Throwable throwable);
132
    void debug(Supplier<?> messageSupplier);
133
    LogBuilder atInfo();
134
    LogBuilder atError();
135
}
136

137
public interface LogBuilder {
138
    LogBuilder withMarker(Marker marker);
139
    LogBuilder withThrowable(Throwable throwable);
140
    LogBuilder withLocation();
141
    void log(String message);
142
    void log(String message, Object... params);
143
}
144
```
145

146
[Performance Features](./performance-features.md)
147

148
### Thread Context Management
149

150
Per-thread context functionality providing both Map (MDC) and Stack (NDC) capabilities for request correlation, user tracking, and contextual logging across application layers.
151

152
```java { .api }
153
public final class ThreadContext {
154
    // Map operations (MDC)
155
    public static void put(String key, String value);
156
    public static String get(String key);
157
    public static void remove(String key);
158
    public static Map<String, String> getContext();
159
    public static void clearMap();
160
    
161
    // Stack operations (NDC) 
162
    public static void push(String message);
163
    public static String pop();
164
    public static String peek();
165
    public static void clearStack();
166
    public static int getDepth();
167
}
168

169
public class CloseableThreadContext {
170
    public static Instance put(String key, String value);
171
    public static Instance push(String message);
172
    
173
    public static class Instance implements AutoCloseable {
174
        public void close();
175
    }
176
}
177
```
178

179
[Thread Context](./thread-context.md)
180

181
### Markers & Filtering
182

183
Marker system for adding hierarchical, filterable metadata to log events. Enables sophisticated filtering and routing based on marker taxonomy.
184

185
```java { .api }
186
public interface Marker extends Serializable {
187
    String getName();
188
    Marker addParents(Marker... markers);
189
    Marker[] getParents();
190
    boolean isInstanceOf(Marker marker);
191
    boolean isInstanceOf(String name);
192
}
193

194
public final class MarkerManager {
195
    public static Marker getMarker(String name);
196
    public static boolean exists(String key);
197
    public static void clear();
198
}
199
```
200

201
[Markers](./markers.md)
202

203
### Message System & Formatting
204

205
Comprehensive message creation system supporting multiple formatting syntaxes, structured data, flow tracing, and custom message factories for specialized use cases.
206

207
```java { .api }
208
public interface Message extends Serializable {
209
    String getFormattedMessage();
210
    Object[] getParameters();
211
    Throwable getThrowable();
212
}
213

214
public interface MessageFactory {
215
    Message newMessage(Object message);
216
    Message newMessage(String message);
217
    Message newMessage(String message, Object... params);
218
}
219

220
// Built-in message types
221
public class ParameterizedMessage implements Message;
222
public class SimpleMessage implements Message;
223
public class ObjectMessage implements Message;
224
public class MapMessage implements Message;
225
public class StructuredDataMessage extends MapMessage;
226
```
227

228
[Message System](./message-system.md)
229

230
### Service Provider Interface
231

232
Extension points for custom logger implementations, context factories, and integration with different logging backends. Enables Log4j API to work with various implementations.
233

234
```java { .api }
235
public interface LoggerContext {
236
    ExtendedLogger getLogger(String name);
237
    boolean hasLogger(String name);
238
    Object getExternalContext();
239
}
240

241
public interface LoggerContextFactory {
242
    LoggerContext getContext(String fqcn, ClassLoader loader, 
243
                           Object externalContext, boolean currentContext);
244
    void removeContext(LoggerContext context);
245
    void shutdown(String fqcn, ClassLoader loader, 
246
                  boolean currentContext, boolean allContexts);
247
}
248

249
public interface ExtendedLogger extends Logger {
250
    void logIfEnabled(String fqcn, Level level, Marker marker, 
251
                     String message, Throwable throwable);
252
}
253
```
254

255
[Service Provider Interface](./spi.md)
256

257
### Status & Error Handling
258

259
Internal status reporting system for Log4j configuration issues, initialization problems, and runtime diagnostics. Essential for troubleshooting logging setup.
260

261
```java { .api }
262
public class StatusLogger implements Logger {
263
    public static StatusLogger getLogger();
264
}
265

266
public interface StatusListener {
267
    void log(StatusData data);
268
    Level getStatusLevel();
269
    void close();
270
}
271

272
public interface StatusData {
273
    long getTimestamp();
274
    Level getLevel();
275
    Message getMessage();
276
    Throwable getThrowable();
277
}
278
```
279

280
[Status System](./status-system.md)