or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-logging.mdindex.mdmarkers.mdmessage-system.mdperformance-features.mdspi.mdstatus-system.mdthread-context.md
tile.json

tessl/maven-org-apache-logging-log4j--log4j-api

The logging API of the Log4j project providing a comprehensive and flexible logging framework for Java applications.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.apache.logging.log4j/log4j-api@2.25.x

To install, run

npx @tessl/cli install tessl/maven-org-apache-logging-log4j--log4j-api@2.25.0

index.mddocs/

Apache Log4j API

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.

Package Information

  • Package Name: org.apache.logging.log4j:log4j-api
  • Package Type: Maven
  • Language: Java
  • Installation: 
    <dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-api</artifactId>
    <version>2.25.1</version>
</dependency>

Core Imports

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

Common additional imports:

import org.apache.logging.log4j.Level;
import org.apache.logging.log4j.Marker;
import org.apache.logging.log4j.MarkerManager;
import org.apache.logging.log4j.ThreadContext;

Basic Usage

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

public class MyApplication {
    private static final Logger logger = LogManager.getLogger(MyApplication.class);
    
    public void doSomething() {
        logger.info("Application started");
        
        try {
            // Application logic
            logger.debug("Processing user data");
            processUserData("user123");
            logger.info("User data processed successfully");
        } catch (Exception e) {
            logger.error("Error processing user data", e);
        }
    }
    
    private void processUserData(String userId) {
        // Parameterized logging for performance
        logger.info("Processing data for user: {}", userId);
        
        // Thread context for request tracking
        ThreadContext.put("userId", userId);
        logger.debug("Added user ID to thread context");
        ThreadContext.clear();
    }
}

Architecture

Log4j API is built around several key components:

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

Capabilities

Core Logging Interface

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.

public final class LogManager {
    public static Logger getLogger();
    public static Logger getLogger(Class<?> clazz);
    public static Logger getLogger(String name);
    public static LoggerContext getContext();
    public static void shutdown();
}

public interface Logger {
    void trace(String message);
    void debug(String message);
    void info(String message);
    void warn(String message);
    void error(String message);
    void fatal(String message);
    void log(Level level, String message);
    boolean isEnabled(Level level);
    String getName();
}

public final class Level implements Comparable<Level> {
    public static final Level OFF;
    public static final Level FATAL;
    public static final Level ERROR;
    public static final Level WARN;
    public static final Level INFO;
    public static final Level DEBUG;
    public static final Level TRACE;
    public static final Level ALL;
    
    public int intLevel();
    public boolean isMoreSpecificThan(Level level);
    public static Level valueOf(String name);
}

Core Logging

Parameterized Logging & Performance

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

public interface Logger {
    void info(String message, Object... params);
    void error(String message, Throwable throwable);
    void debug(Supplier<?> messageSupplier);
    LogBuilder atInfo();
    LogBuilder atError();
}

public interface LogBuilder {
    LogBuilder withMarker(Marker marker);
    LogBuilder withThrowable(Throwable throwable);
    LogBuilder withLocation();
    void log(String message);
    void log(String message, Object... params);
}

Performance Features

Thread Context Management

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

public final class ThreadContext {
    // Map operations (MDC)
    public static void put(String key, String value);
    public static String get(String key);
    public static void remove(String key);
    public static Map<String, String> getContext();
    public static void clearMap();
    
    // Stack operations (NDC) 
    public static void push(String message);
    public static String pop();
    public static String peek();
    public static void clearStack();
    public static int getDepth();
}

public class CloseableThreadContext {
    public static Instance put(String key, String value);
    public static Instance push(String message);
    
    public static class Instance implements AutoCloseable {
        public void close();
    }
}

Thread Context

Markers & Filtering

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

public interface Marker extends Serializable {
    String getName();
    Marker addParents(Marker... markers);
    Marker[] getParents();
    boolean isInstanceOf(Marker marker);
    boolean isInstanceOf(String name);
}

public final class MarkerManager {
    public static Marker getMarker(String name);
    public static boolean exists(String key);
    public static void clear();
}

Markers

Message System & Formatting

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

public interface Message extends Serializable {
    String getFormattedMessage();
    Object[] getParameters();
    Throwable getThrowable();
}

public interface MessageFactory {
    Message newMessage(Object message);
    Message newMessage(String message);
    Message newMessage(String message, Object... params);
}

// Built-in message types
public class ParameterizedMessage implements Message;
public class SimpleMessage implements Message;
public class ObjectMessage implements Message;
public class MapMessage implements Message;
public class StructuredDataMessage extends MapMessage;

Message System

Service Provider Interface

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

public interface LoggerContext {
    ExtendedLogger getLogger(String name);
    boolean hasLogger(String name);
    Object getExternalContext();
}

public interface LoggerContextFactory {
    LoggerContext getContext(String fqcn, ClassLoader loader, 
                           Object externalContext, boolean currentContext);
    void removeContext(LoggerContext context);
    void shutdown(String fqcn, ClassLoader loader, 
                  boolean currentContext, boolean allContexts);
}

public interface ExtendedLogger extends Logger {
    void logIfEnabled(String fqcn, Level level, Marker marker, 
                     String message, Throwable throwable);
}

Service Provider Interface

Status & Error Handling

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

public class StatusLogger implements Logger {
    public static StatusLogger getLogger();
}

public interface StatusListener {
    void log(StatusData data);
    Level getStatusLevel();
    void close();
}

public interface StatusData {
    long getTimestamp();
    Level getLevel();
    Message getMessage();
    Throwable getThrowable();
}

Status System