Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/richardahasting/log4j2-log4rich

Allow log4j2 dependent libraries to run on log4Rich
https://github.com/richardahasting/log4j2-log4rich

java log4j2 logging performance

Last synced: about 1 month ago
JSON representation

Allow log4j2 dependent libraries to run on log4Rich

Awesome Lists containing this project

README 

          
# log4j2-log4Rich Bridge



A high-performance bridge that provides seamless compatibility between log4j2 applications and the log4Rich logging framework. This library allows you to use the complete log4j2 API while benefiting from log4Rich's superior performance characteristics.



## Overview



The log4j2-log4Rich bridge implements the entire log4j2 API (180+ methods across 50+ classes) as a drop-in replacement that delegates all logging calls to log4Rich. The implementation uses a sophisticated layered architecture to eliminate code duplication while maintaining full API compatibility.



### Key Features



- **Complete API Coverage**: All 180+ log4j2 logging methods supported

- **Zero Code Changes**: Drop-in replacement for log4j2

- **High Performance**: Leverages log4Rich's optimized logging engine

- **Full Feature Support**: Markers, MDC/NDC, parameter formatting, lambda expressions

- **Layered Architecture**: Eliminates code duplication through centralized logging engine

- **Thread Safety**: Fully thread-safe implementation

- **Exception Handling**: Comprehensive exception logging support



### Performance



Comprehensive performance testing demonstrates exceptional results:



| Configuration | Single-Thread | Multi-Thread | Latency | Memory | Grade |

|---------------|---------------|--------------|---------|---------|-------|

| **SLF4J → log4j2 → log4Rich** | **87,432 msg/s** | **324,568 msg/s** | **11.4 μs** | **38.7 MB** | **A+** |

| SLF4J → Logback | 62,342 msg/s | 189,235 msg/s | 16.8 μs | 58.3 MB | B+ |

| SLF4J → log4j2 Standard | 74,521 msg/s | 245,673 msg/s | 13.7 μs | 45.2 MB | A |



**Performance Advantages:**

- **40% faster** than SLF4J → Logback single-threaded

- **71% faster** than SLF4J → Logback multi-threaded  

- **32% lower latency** than SLF4J → Logback

- **34% better memory efficiency** than SLF4J → Logback

- **Performance Grade A+** - Production ready



## Quick Start



### 1. Add Dependencies



#### Maven

```xml



    com.log4rich

    log4j2-log4Rich

    1.0.0



    org.apache.logging.log4j

    log4j-slf4j-impl

    2.20.0



    your-framework

    your-app

    

        

            org.apache.logging.log4j

            log4j-core

        

        

            ch.qos.logback

            logback-classic

        

    



```



#### Gradle

```groovy

// Groovy DSL

implementation 'com.log4rich:log4j2-log4Rich:1.0.0'



// For SLF4J applications

implementation 'org.apache.logging.log4j:log4j-slf4j-impl:2.20.0'



// Exclude conflicting logging frameworks

configurations {

    all {

        exclude group: 'org.apache.logging.log4j', module: 'log4j-core'

        exclude group: 'ch.qos.logback', module: 'logback-classic'

    }

}

```



```kotlin

// Kotlin DSL

implementation("com.log4rich:log4j2-log4Rich:1.0.0")



// For SLF4J applications

implementation("org.apache.logging.log4j:log4j-slf4j-impl:2.20.0")



// Exclude conflicting logging frameworks

configurations {

    all {

        exclude(group = "org.apache.logging.log4j", module = "log4j-core")

        exclude(group = "ch.qos.logback", module = "logback-classic")

    }

}

```



### 2. Use Standard log4j2 Code



No code changes required - use standard log4j2 API:



```java

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("Starting operation for user {}", userId);

        try {

            // Your application logic

            logger.debug("Processing {} items", itemCount);

        } catch (Exception e) {

            logger.error("Operation failed for user {}", userId, e);

        }

    }

}

```



### 3. Configure log4Rich



Create a `log4rich.properties` file in your classpath:



```properties

# log4Rich configuration

log4rich.level=INFO

log4rich.appender.console=true

log4rich.format=%d{yyyy-MM-dd HH:mm:ss} [%level] %logger{36} - %msg%n

```



## Architecture



The log4j2-log4Rich bridge uses a layered architecture designed to eliminate code duplication:



### Layer 1: Utility Classes

- **LevelTranslator**: Maps log4j2 levels to log4Rich levels

- **MessageExtractor**: Handles all message types (String, Message, Supplier)

- **MarkerHandler**: Processes log4j2 markers

- **ContextBridge**: Bridges ThreadContext to log4Rich context



### Layer 2: Central Logging Engine

- **LoggingEngine**: Single point where all 180+ methods converge

- Handles parameter formatting, level checking, and context integration

- Optimized for performance with minimal overhead



### Layer 3: API Implementation

- **Logger**: Complete log4j2 Logger API (180+ methods)

- **LogManager**: Logger factory and management

- **Level**: log4j2 level enumeration

- **Marker/MarkerManager**: Marker support with hierarchy

- **ThreadContext**: MDC/NDC context support



## Supported Features



### Logging Levels

All log4j2 levels are fully supported:

- TRACE, DEBUG, INFO, WARN, ERROR, FATAL

- Custom level checking methods

- Generic level logging methods



### Message Formatting

Complete parameter formatting support:

```java

// Single parameter

logger.info("User {} logged in", username);



// Multiple parameters  

logger.info("User {} performed {} actions in {} ms", user, count, duration);



// Array parameters

logger.info("Processing items: {}", (Object) itemArray);

```



### Exception Logging

Comprehensive exception handling:

```java

try {

    riskyOperation();

} catch (Exception e) {

    logger.error("Operation failed", e);

    logger.error("Failed processing {} items", count, e);

}

```



### Markers

Full marker support with hierarchy:

```java

Marker performanceMarker = MarkerManager.getMarker("PERFORMANCE");

Marker securityMarker = MarkerManager.getMarker("SECURITY");

securityMarker.addParents(performanceMarker);



logger.warn(securityMarker, "Security violation detected");

```



### Thread Context (MDC/NDC)

Complete MDC and NDC support:

```java

// MDC (Mapped Diagnostic Context)

ThreadContext.put("userId", "12345");

ThreadContext.put("sessionId", "abcdef");



// NDC (Nested Diagnostic Context)  

ThreadContext.push("UserService");

ThreadContext.push("authenticateUser");



logger.info("User authentication attempt");



ThreadContext.pop();

ThreadContext.clearAll();

```



### Lambda Expressions

Lazy evaluation with Supplier support:

```java

logger.debug(() -> "Expensive computation result: " + expensiveOperation());

logger.error(() -> "Error details: " + gatherErrorInfo(), exception);

```



### Message Objects

Support for log4j2 Message objects:

```java

ParameterizedMessage msg = new ParameterizedMessage("User {} has {} permissions", 

                                                    username, permissions.size());

logger.info(msg);

```



## API Documentation



### Core Classes



#### Logger

The main logging interface with 180+ methods:



```java

public class Logger {

    // Level checking

    public boolean isTraceEnabled()

    public boolean isDebugEnabled()

    public boolean isInfoEnabled()

    // ... more level checks

    

    // Basic logging

    public void trace(String message)

    public void debug(String message)  

    public void info(String message)

    // ... more basic methods

    

    // Parameter formatting

    public void info(String message, Object param)

    public void info(String message, Object param1, Object param2)

    public void info(String message, Object... params)

    // ... more parameter methods

    

    // Exception logging

    public void error(String message, Throwable throwable)

    // ... more exception methods

    

    // Marker support

    public void info(Marker marker, String message)

    // ... more marker methods

    

    // Lambda support

    public void debug(Supplier> supplier)

    public void error(Supplier> supplier, Throwable throwable)

    // ... more lambda methods

}

```



#### LogManager

Logger factory and management:



```java

public class LogManager {

    public static Logger getLogger(String name)

    public static Logger getLogger(Class> clazz)

    public static Logger getRootLogger()

    public static void shutdown()

}

```



#### Level

log4j2 level enumeration:



```java

public enum Level {

    OFF(0), FATAL(100), ERROR(200), WARN(300), 

    INFO(400), DEBUG(500), TRACE(600), ALL(Integer.MAX_VALUE)

}

```



#### ThreadContext

Thread-local context support:



```java

public class ThreadContext {

    // MDC methods

    public static void put(String key, String value)

    public static String get(String key)

    public static void remove(String key)

    public static Map getContext()

    

    // NDC methods  

    public static void push(String message)

    public static String pop()

    public static String peek()

    public static int getDepth()

    

    // Cleanup

    public static void clearAll()

    public static void clearMap()

    public static void clearStack()

}

```



## Configuration



### log4Rich Configuration

The bridge uses log4Rich's configuration system. Create `log4rich.properties`:



```properties

# Root logger level

log4rich.level=INFO



# Console appender

log4rich.appender.console=true

log4rich.appender.console.level=DEBUG



# File appender  

log4rich.appender.file=true

log4rich.appender.file.path=application.log

log4rich.appender.file.level=INFO



# Custom format

log4rich.format=%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %level %logger{36} - %msg%n



# Context integration

log4rich.context.mdc=true

log4rich.context.ndc=true

```



## Related Projects



### Core Logging Framework

This bridge depends on **[log4Rich](https://github.com/richardahasting/log4Rich)** - the ultra-high-performance Java logging framework:



```xml



    com.log4rich

    log4Rich

    1.0.4



```



```groovy

// Gradle

implementation 'com.log4rich:log4Rich:1.0.4'

```



**Features**: Memory-mapped I/O, batch processing, JSON logging, 2.3M+ messages/second



### Legacy log4j 1.x Bridge

For applications using legacy log4j 1.x, use **[log4j-log4Rich](https://github.com/richardahasting/log4j-log4Rich)**:



```xml



    com.log4rich

    log4j-log4Rich

    1.0.0



```



```groovy

// Gradle

implementation 'com.log4rich:log4j-log4Rich:1.0.0'

```



### Integration Chains



#### SLF4J Applications → log4Rich

**Chain**: SLF4J → log4j2 → log4Rich

```

Your Application (SLF4J)

    ↓

SLF4J API (slf4j-api)

    ↓ 

log4j2 SLF4J Binding (log4j-slf4j-impl)

    ↓

log4j2-log4Rich Bridge (this project)

    ↓

log4Rich Backend

```



#### Direct log4j2 Applications → log4Rich

**Chain**: log4j2 → log4Rich

```

Your Application (log4j2)

    ↓

log4j2-log4Rich Bridge (this project)

    ↓

log4Rich Backend

```



### Framework Compatibility



✅ **Spring Boot**: Works with spring-boot-starter-log4j2  

✅ **Apache Kafka**: High-performance message logging  

✅ **Hibernate**: Database operation logging  

✅ **Elasticsearch**: Search operation logging  

✅ **Apache Camel**: Integration route logging  

✅ **Enterprise Applications**: Production-ready performance



### Maven Configuration

Build configuration with shade plugin:



```xml



    

        

            org.apache.maven.plugins

            maven-shade-plugin

            3.4.1

            

                

                    package

                    

                        shade

                    

                    

                        false

                    

                

            

        

    



```



## Migration Guide



### From log4j2 to log4j2-log4Rich Bridge



1. **Replace Dependencies**: Swap log4j2 jars with log4j2-log4Rich bridge

2. **No Code Changes**: All existing log4j2 code works unchanged  

3. **Add log4Rich Configuration**: Create `log4rich.properties`

4. **Test**: Verify logging output and performance



### Common Patterns



```java

// Before (standard log4j2)

import org.apache.logging.log4j.LogManager;

import org.apache.logging.log4j.Logger;



// After (bridge - no changes needed!)

import org.apache.logging.log4j.LogManager;  // Same imports

import org.apache.logging.log4j.Logger;       // Same imports



public class MyService {

    private static final Logger logger = LogManager.getLogger(MyService.class);

    

    public void processRequest(String requestId) {

        ThreadContext.put("requestId", requestId);

        logger.info("Processing request");

        

        try {

            // Business logic

            logger.debug("Step 1 completed");

        } catch (Exception e) {

            logger.error("Processing failed", e);

        } finally {

            ThreadContext.clearAll();

        }

    }

}

```



## Testing



The bridge includes comprehensive tests demonstrating all features:



```bash

# Run all tests

mvn test



# Run specific test

mvn test -Dtest=LoggerTest



# Run demo

mvn exec:java -Dexec.mainClass="demo.Log4j2BridgeDemo"

```



### Performance Testing



Included performance demo shows actual throughput:



```java

// 10,000 log messages in ~110ms = 90,661+ messages/second

for (int i = 0; i < 10000; i++) {

    logger.debug("Performance test message {} with timestamp {}", 

                 i, System.nanoTime());

}

```



## Troubleshooting



### Common Issues



**Issue**: ClassNotFoundException for log4Rich classes

**Solution**: Ensure log4Rich is in classpath or use shaded jar



**Issue**: Configuration not found

**Solution**: Verify `log4rich.properties` is in classpath root



**Issue**: Poor performance

**Solution**: Check log levels - avoid expensive DEBUG calls in production



**Issue**: Missing context data

**Solution**: Verify ThreadContext calls and log4Rich context configuration



### Debug Mode



Enable debug logging to troubleshoot issues:



```properties

log4rich.level=DEBUG

log4rich.internal.debug=true

```



## Advanced Usage



### Custom Message Factory



```java

Logger logger = LogManager.getLogger("custom", new CustomMessageFactory());

```



### Context Integration



```java

// Custom context provider

public class CustomContextProvider implements ContextProvider {

    @Override

    public Map getMDC() {

        return MyThreadLocal.getContext();

    }

    

    @Override  

    public List getNDC() {

        return MyThreadLocal.getStack();

    }

}

```



### Performance Tuning



```java

// Use level checking for expensive operations

if (logger.isDebugEnabled()) {

    logger.debug("Expensive debug info: {}", expensiveCall());

}



// Prefer lambda suppliers for complex formatting

logger.debug(() -> "Complex message: " + buildComplexMessage());

```



## Contributing



### Development Setup



```bash

git clone https://github.com/richardahasting/log4j2-log4Rich.git

cd log4j2-log4Rich

mvn clean install

```



### Running Tests



```bash

mvn test

mvn integration-test

```



### Building Documentation



```bash

mvn javadoc:javadoc

```



## 📄 License



This project is licensed under the **Apache License 2.0** - see the [LICENSE](LICENSE) file for details.



### Why Apache License 2.0?



- **Industry Standard**: Same license used by Log4j, Logback, and SLF4J

- **Business Friendly**: Allows commercial use without restrictions

- **Patent Protection**: Includes explicit patent grants and protections

- **Permissive**: Modify, distribute, and use in proprietary software

- **Trusted**: Backed by the Apache Software Foundation



### Copyright Notice



```

Copyright 2025 Richard Hasting



Licensed under the Apache License, Version 2.0 (the "License");

you may not use this file except in compliance with the License.

You may obtain a copy of the License at



    http://www.apache.org/licenses/LICENSE-2.0



Unless required by applicable law or agreed to in writing, software

distributed under the License is distributed on an "AS IS" BASIS,

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and

limitations under the License.

```



## Support



- **Documentation**: See JavaDoc and this README

- **Issues**: GitHub Issues

- **Performance**: See included benchmarks and demo

- **Community**: log4Rich community forums