Ever found yourself writing `private static final Logger log = LoggerFactory.getLogger(MyClass.class);` for the hundredth time and thinking, "There has to be a better way"? Or maybe you've watched your high-throughput Java app grind to a halt because logging became a bottleneck? Yeah, we've been there too. **Hermes** is a modern logging library for Java 17+ that ditches the old baggage. No more boilerplate logger declarations. No more XML config files. No more lock contention killing your throughput. Instead, you get compile-time code generation, zero-allocation message formatting, and lock-free async processing via LMAX Disruptor. Named after the Greek messenger god who delivered messages at lightning speed, Hermes does exactly that for your logs. ## Why Hermes? Look, most logging frameworks were built back in the Java 6 days. They work, sure, but they weren't designed for today's cloud-native, high-throughput world. If you're running microservices that handle thousands of requests per second, or processing millions of Kafka messages per hour, traditional logging can become your bottleneck. ### The Logging Performance Problem Think about what happens every time you log something: format a message, acquire a lock, allocate strings, write to disk. Multiply that by a million events per second. Suddenly, those microseconds add up. Here's what goes wrong with traditional approaches: - **Reflection overhead** for logger field injection - **Lock contention** in multi-threaded async appenders - **GC pressure** from excessive string allocation during message formatting - **Thread blocking** when writing to I/O streams synchronously - **Configuration complexity** with XML or properties files ### Zero-Boilerplate Development Okay, let's talk about the elephant in the room: that logger declaration you copy-paste into every single class. You know the one. And you know how easy it is to forget to change the class name, right? We've all been there. Hermes fixes this with one simple annotation: ```java path=null start=null @InjectLogger public class UserService extends UserServiceHermesLogger { public void createUser(String username) { log.info("Creating user: {}", username); } } ``` That's it. The `@InjectLogger` annotation triggers compile-time code generation that creates a base class with a `protected Logger log` field ready to use. What's cool about this? - **No boilerplate** — Zero. Nada. And no runtime reflection overhead either. - **Type-safe** — Catches errors at compile time, not at 3 AM in production. - **GraalVM-friendly** — Works with native images out of the box. - **IDE-friendly** — Your IDE's autocomplete just works. ### Production-Ready Features Speed is great, but you also need this thing to actually work in production, right? Hermes has you covered: - **Structured JSON logging** — Works seamlessly with ELK, Splunk, Datadog, and friends. - **MDC support** — Track requests across your distributed system. - **Multiple appenders** — Console, File, RollingFile, Async, Logstash—take your pick. - **Flexible formatting** — Customize patterns however you like. - **Spring Boot integration** — Auto-configuration via YAML. No XML nightmares. - **Kotlin DSL** — Because Kotlin developers deserve nice things too. - **GraalVM support** — Native images? Yeah, that works. ## Core Architecture Hermes uses a modular architecture split into six focused modules. You only include what you need, and the dependency boundaries are crystal clear. ### System Architecture Overview ```plantuml @startuml Hermes System Architecture !theme plain package "Application Layer" { [User Application Code] [@InjectLogger Classes] } package "Hermes API (hermes-api)" { [Logger Interface] [LoggerFactory] [MDC & Markers] [@InjectLogger Annotation] } package "Hermes Processor (hermes-processor)" { [Annotation Processor] [Code Generator] } package "Hermes Core (hermes-core)" { [HermesLogger Implementation] [MessageFormatter] [LogEvent (Java Record)] package "Appenders" { [ConsoleAppender] [FileAppender] [RollingFileAppender] [AsyncAppender] [LogstashAppender] } package "Layouts" { [PatternLayout] [JsonLayout] } [LMAX Disruptor Integration] } package "Integration Modules" { [Spring Boot Starter\n(hermes-spring-boot-starter)] [Kotlin DSL\n(hermes-kotlin)] } package "Service Provider Interface" { [LoggerProvider SPI] [ServiceLoader Discovery] } [User Application Code] --> [Logger Interface] [@InjectLogger Classes] ..> [Annotation Processor] : compile-time [Annotation Processor] --> [Code Generator] [Logger Interface] --> [LoggerFactory] [LoggerFactory] --> [ServiceLoader Discovery] [ServiceLoader Discovery] --> [LoggerProvider SPI] [LoggerProvider SPI] --> [HermesLogger Implementation] [HermesLogger Implementation] --> [MessageFormatter] [HermesLogger Implementation] --> [LogEvent (Java Record)] [LogEvent (Java Record)] --> [ConsoleAppender] [LogEvent (Java Record)] --> [FileAppender] [LogEvent (Java Record)] --> [RollingFileAppender] [LogEvent (Java Record)] --> [AsyncAppender] [LogEvent (Java Record)] --> [LogstashAppender] [ConsoleAppender] --> [PatternLayout] [ConsoleAppender] --> [JsonLayout] [FileAppender] --> [PatternLayout] [FileAppender] --> [JsonLayout] [RollingFileAppender] --> [PatternLayout] [RollingFileAppender] --> [JsonLayout] [AsyncAppender] --> [PatternLayout] [AsyncAppender] --> [JsonLayout] [LogstashAppender] --> [JsonLayout] [AsyncAppender] --> [LMAX Disruptor Integration] [Spring Boot Starter\n(hermes-spring-boot-starter)] --> [HermesLogger Implementation] [Kotlin DSL\n(hermes-kotlin)] --> [Logger Interface] note right of [ServiceLoader Discovery] Decouples API from implementation using Java's ServiceLoader mechanism for runtime provider discovery end note note right of [LMAX Disruptor Integration] Lock-free ring buffer enables 10M+ logs/sec throughput with wait-free publish semantics end note @enduml ``` ### Module Dependency Structure Hermes is organized into six distinct modules, each with specific responsibilities: ```plantuml @startuml Module Dependencies !theme plain package "hermes-api" as API { [Logger Interface] [LoggerFactory] [@InjectLogger] [MDC/Markers] } package "hermes-processor" as PROC { [Annotation Processor] note right: Compile-time only } package "hermes-core" as CORE { [HermesLogger] [Appenders] [Layouts] [Disruptor] } package "hermes-spring-boot-starter" as SPRING { [Auto-Configuration] [YAML Properties] } package "hermes-kotlin" as KOTLIN { [Extension Functions] [DSL Builders] } package "hermes-examples" as EXAMPLES { [Demo Applications] } PROC ..> API : depends on CORE --> API : implements SPRING --> API : depends on SPRING --> CORE : runtime KOTLIN --> API : extends EXAMPLES --> API : uses EXAMPLES --> CORE : runtime EXAMPLES --> PROC : compile-time note bottom of API Public contract - users compile against this No dependencies on implementation details end note note bottom of CORE Runtime implementation discovered via ServiceLoader - never directly referenced end note @enduml ``` #### Module Breakdown **1. hermes-api** - The Public Contract Contains all public interfaces, annotations, and API surface that applications compile against. This separation enables implementation swapping without recompilation. **Key components:** - `Logger` interface with level-specific methods (trace, debug, info, warn, error) - `LoggerFactory` for logger instantiation - `@InjectLogger` annotation for compile-time injection - `LogLevel` enum (TRACE, DEBUG, INFO, WARN, ERROR) - `MDC` (Mapped Diagnostic Context) for thread-local contextual data - `Marker` interface for log categorization **2. hermes-core** - The Implementation Engine Provides the concrete implementation of all logging functionality, optimized for performance and zero-allocation where possible. **Key components:** - `HermesLogger` - Main logger implementation with level checks - `LogEvent` - Immutable Java 17 record capturing log data - `MessageFormatter` - Zero-allocation message formatting using ThreadLocal StringBuilder - **Appenders**: Console, File, RollingFile, Async (with Disruptor), Logstash - **Layouts**: Pattern (customizable format strings), JSON (structured logging) - Performance optimizations: early exit, ThreadLocal reuse, lock-free data structures **3. hermes-processor** - Compile-Time Code Generation Annotation processor that generates logger base classes during compilation, eliminating runtime reflection overhead. **How it works:** 1. Detects `@InjectLogger` annotation during compilation 2. Generates a base class (e.g., `UserServiceHermesLogger`) with `protected Logger log` field 3. User class extends the generated base class to access the logger 4. No runtime overhead—all code generation happens at compile time **4. hermes-spring-boot-starter** - Spring Boot Integration Auto-configuration module providing seamless Spring Boot integration with property binding and lifecycle management. **Features:** - `@EnableAutoConfiguration` support - `HermesProperties` for YAML/properties binding - Actuator health indicator for monitoring - Automatic logger configuration from `application.yml` **5. hermes-kotlin** - Idiomatic Kotlin Extensions Kotlin DSL providing idiomatic syntax for Kotlin projects using extension functions and builders. **Features:** - `MyClass::class.logger` - Extension property for logger creation - Lazy evaluation: `log.info { "Expensive $computation" }` - MDC DSL: `withMDC("key" to "value") { ... }` - Structured logging builders with type-safe key-value pairs **6. hermes-examples** - Reference Implementations Working examples demonstrating various Hermes features and integration patterns. ## High-Performance Async Logging with LMAX Disruptor Here's the thing: most async logging uses lock-based queues. They work okay for moderate loads, but when you're pushing millions of logs per second, those locks become a serious bottleneck. Thread contention, context switching—it all adds up. Hermes uses the [LMAX Disruptor](https://lmax-exchange.github.io/disruptor/) instead. If you haven't heard of it, it's the same tech that powers financial trading systems where nanoseconds matter. It's lock-free, wait-free, and absurdly fast. ### Async Logging Flow The asynchronous logging process is designed to minimize application thread latency while maximizing throughput: ### Performance Characteristics **Application Thread (Publisher)** - **Latency**: ~100 nanoseconds (wait-free publish) - **Non-blocking**: Returns immediately after publishing to ring buffer - **No locks**: Uses CAS (Compare-And-Swap) operations **Background Thread (Consumer)** - **Batching**: Processes multiple events together, amortizing overhead - **Sequential I/O**: Writes are coalesced for better disk throughput - **Single consumer**: Eliminates coordination overhead **Throughput Comparison** - **`ArrayBlockingQueue` (lock-based)** - Throughput: ~1M logs/sec - Latency: ~5-10 µs - **LMAX Disruptor (lock-free)** - Throughput: **10M+ logs/sec** - Latency: **~0.1 µs** ### Ring Buffer Mechanics The ring buffer is pre-allocated with a fixed size (power of 2, typically 1024-8192 slots). This design provides several advantages: 1. **Memory locality**: Contiguous memory improves CPU cache utilization 2. **No allocation**: Slots are reused, eliminating GC pressure 3. **Fast modulo**: Ring wrapping uses bitwise AND instead of expensive modulo operation 4. **Wait-free**: Publishers never wait for consumers (unless buffer full) ## Zero-Allocation Message Formatting Every time traditional logging formats a message, it creates new String objects. One log message? No big deal. A million per second? Now you've got a garbage collection nightmare. Hermes fixes this by reusing ThreadLocal StringBuilder instances. After the initial allocation, it's zero-copy formatting all the way down. ### Performance Impact **Before (Traditional Approach)** ```java path=null start=null // Creates 3 new String objects per call log.info("User " + username + " logged in at " + timestamp); ``` - **Allocations**: 3+ String objects, intermediate char arrays - **GC pressure**: Continuous young generation collections - **Throughput impact**: GC pauses affect latency **After (Hermes Zero-Allocation)** ```java path=null start=null // Zero allocations using ThreadLocal StringBuilder reuse log.info("User {} logged in at {}", username, timestamp); ``` - **Allocations**: Zero (after first call per thread) - **GC pressure**: Minimal—only final String and LogEvent allocated - **Throughput**: No GC pauses from message formatting ### Implementation Details ```java path=null start=null public class MessageFormatter { // ThreadLocal ensures each thread has its own StringBuilder private static final ThreadLocal BUFFER = ThreadLocal.withInitial(() -> new StringBuilder(256)); public static String format(String pattern, Object... args) { StringBuilder sb = BUFFER.get(); sb.setLength(0); // Clear but don't deallocate int argIndex = 0; int patternLength = pattern.length(); for (int i = 0; i < patternLength; i++) { char c = pattern.charAt(i); if (c == '{' && i + 1 < patternLength && pattern.charAt(i + 1) == '}') { // Placeholder found if (argIndex < args.length) { sb.append(args[argIndex++]); } i++; // Skip the '}' } else { sb.append(c); } } return sb.toString(); // Only allocation } } ``` ## Spring Boot Integration If you're using Spring Boot (and let's be honest, you probably are), Hermes plays nice right out of the box. No complex setup, no XML files to wrestle with—just add the starter and configure via YAML. ### Configuration Example ```yaml path=null start=null # application.yml hermes: # Root log level and package-specific levels level: root: INFO packages: io.github.dotbrains: DEBUG com.myapp.service: TRACE com.myapp.repository: DEBUG # Log output pattern (supports multiple format directives) pattern: "%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n" # Async logging configuration async: enabled: true queue-size: 2048 # Ring buffer size (must be power of 2) ``` ### Pattern Format Directives - **`%d{pattern}`** - Timestamp (e.g., `2026-01-10 11:45:30.123`) - **`%thread`** - Thread name (e.g., `http-nio-8080-exec-1`) - **`%level`** - Log level (e.g., `INFO`) - **`%-5level`** - Left-aligned level, 5 chars (e.g., `INFO `) - **`%logger{length}`** - Logger name, abbreviated (e.g., `c.e.s.UserService`) - **`%msg`** - Log message (e.g., `User created successfully`) - **`%n`** - Line separator (platform-specific) - **`%mdc{key}`** - MDC value (e.g., `req-12345`) - **`%exception`** - Exception stack trace (full stack trace) ## Structured JSON Logging If you're shipping logs to ELK, Splunk, Datadog, or any modern observability platform, you need JSON. Not because it's trendy, but because it's the only way to make your logs actually queryable and useful. Hermes has built-in JSON formatting that's optimized for these platforms: ### JSON Output Example ```json path=null start=null { "timestamp": "2026-01-10T04:58:51.123Z", "level": "INFO", "logger": "com.example.UserService", "thread": "http-nio-8080-exec-1", "threadId": "42", "message": "User john.doe created successfully", "mdc": { "requestId": "req-789", "userId": "12345", "sessionId": "sess-abc" } } ``` ### Logstash Integration Hermes includes a dedicated LogstashAppender for direct TCP streaming to Logstash: ```java path=null start=null LogstashAppender logstash = new LogstashAppender( "logstash", "logstash.example.com", // Logstash host 5000 // TCP input port ); logstash.start(); ``` **Logstash Configuration:** ```ruby path=null start=null input { tcp { port => 5000 codec => json } } filter { # Add additional fields, parse timestamps, etc. mutate { add_field => { "environment" => "production" } } } output { elasticsearch { hosts => ["elasticsearch:9200"] index => "hermes-logs-%{+YYYY.MM.dd}" } } ``` ## Kotlin DSL Writing Kotlin? You shouldn't have to suffer through a Java logging API. Hermes includes a dedicated Kotlin module with extension functions and DSL builders that feel natural in Kotlin code. ### Kotlin Extensions Overview ```kotlin path=null start=null import io.github.dotbrains.kotlin.* class UserService { // Extension property for logger creation private val log = UserService::class.logger fun createUser(userId: String, username: String) { // Lazy evaluation - only computed if DEBUG enabled log.debug { "Creating user with expensive data: ${expensiveOperation()}" } // MDC with automatic cleanup withMDC("userId" to userId, "username" to username) { log.info { "Processing user creation" } // MDC is automatically cleared after block } // Structured logging DSL log.infoWith { "message" to "User created successfully" "userId" to userId "username" to username "timestamp" to System.currentTimeMillis() "environment" to System.getenv("ENV") } } // Exception logging with Kotlin syntax fun handleError(userId: String, error: Exception) { log.error(error) { "Failed to process user: $userId" } } } ``` ### Lazy Evaluation Benefits Kotlin's lambda syntax enables true lazy evaluation—expensive operations are only executed if the log level is enabled: ```kotlin path=null start=null // ❌ BAD: expensiveOperation() always called, even if DEBUG disabled log.debug("Result: ${expensiveOperation()}") // ✅ GOOD: expensiveOperation() only called if DEBUG enabled log.debug { "Result: ${expensiveOperation()}" } ``` ## GraalVM Native Image Support Hermes includes GraalVM native-image metadata for ahead-of-time compilation to native executables, eliminating the need for manual reflection configuration. ### Native Image Metadata Hermes includes the following metadata in `hermes-core/src/main/resources/META-INF/native-image/`: **reflect-config.json** - Reflection hints ```json path=null start=null [ { "name": "io.github.dotbrains.core.HermesLoggerProvider", "allPublicMethods": true } ] ``` **resource-config.json** - Resource patterns ```json path=null start=null { "resources": { "includes": [ { "pattern": "META-INF/services/.*" }, { "pattern": "application.ya?ml" } ] } } ``` ### Building Native Images ```bash path=null start=null # Maven with GraalVM native plugin mvn -Pnative native:compile # Gradle with GraalVM native plugin ./gradlew nativeCompile # Direct native-image invocation native-image --no-fallback -jar myapp.jar ``` ## Performance Benchmarks and Metrics Hermes is designed for high-performance scenarios. Here are the expected performance characteristics: ### Latency Measurements - **Disabled log statement**: ~1 ns (level check only, early exit) - **Enabled sync log (console)**: ~1-5 µs (message formatting + I/O) - **Enabled async log (Disruptor)**: ~100 ns (wait-free publish to ring buffer) - **JSON formatting**: ~2-10 µs (object construction + serialization) - **File write (buffered)**: ~5-20 µs (depends on I/O buffer size) ### Throughput Comparison - **Sync console logging**: ~1M logs/sec (single thread, pattern layout) - **Async file logging**: ~10M+ logs/sec (multiple threads, Disruptor, buffered I/O) - **JSON structured logging**: ~500K logs/sec (single thread, JSON layout) ### Memory Efficiency **Before (Traditional Logging)** - String allocation per log message - Intermediate object creation during formatting - GC pressure from short-lived objects **After (Hermes Optimization)** - ThreadLocal StringBuilder reuse (zero allocation after warmup) - Immutable LogEvent records (compact memory layout) - Pre-allocated ring buffer (no allocation during logging) ## Use Cases and Deployment Scenarios Hermes excels in various production scenarios where logging performance and developer experience matter: ### High-Throughput Microservices **Scenario**: REST API handling 10K+ requests/second with detailed request tracing. **Solution**: - Async appender with Disruptor for non-blocking logging - MDC for request correlation (`requestId`, `userId`, `sessionId`) - JSON layout for structured logs sent to ELK stack **Benefits**: - Application threads return immediately (sub-microsecond logging) - Request tracing across distributed services via MDC propagation - Efficient log querying in Elasticsearch using structured fields ### Data Processing Pipelines **Scenario**: Apache Kafka consumer processing millions of messages per hour with detailed progress tracking. **Solution**: - Rolling file appender with size-based rotation - Zero-allocation message formatting to minimize GC pauses - Conditional debug logging for problematic message inspection **Benefits**: - Minimal overhead on message processing throughput - Automatic log rotation prevents disk exhaustion - Debug logging enabled dynamically without restarts ### Spring Boot Enterprise Applications **Scenario**: Monolithic Spring Boot application with complex business logic requiring comprehensive audit logging. **Solution**: - Spring Boot starter for auto-configuration - YAML-based configuration for environment-specific settings - Multiple appenders (console for dev, file + Logstash for production) - MDC populated via Spring interceptors for request tracking **Benefits**: - Zero-boilerplate logger injection with `@InjectLogger` - Environment-specific configuration without code changes - Seamless integration with Spring Boot Actuator ### Kotlin-Based Applications **Scenario**: Modern Kotlin microservice requiring idiomatic logging syntax. **Solution**: - Kotlin DSL with lazy evaluation and structured logging builders - Extension functions for logger creation - MDC DSL for contextual data **Benefits**: - Lazy evaluation prevents unnecessary computation - Type-safe structured logging with DSL builders - Cleaner code with Kotlin-idiomatic syntax ## Technical Highlights ### What Sets Hermes Apart **1. Compile-Time Logger Injection** - Zero runtime overhead through annotation processing - Type-safe generated base classes - GraalVM-friendly (no reflection configuration) **2. Lock-Free Async Processing** - LMAX Disruptor for 10-100x better throughput than lock-based queues - Wait-free publish semantics - Single consumer pattern eliminates coordination overhead **3. Zero-Allocation Formatting** - ThreadLocal StringBuilder reuse - Early exit for disabled log levels - Minimal GC pressure **4. Modern Java Features** - Java 17 records for immutable, compact LogEvent - ServiceLoader pattern for decoupled architecture - Text blocks for readable configuration **5. Comprehensive Integration** - Spring Boot auto-configuration - Kotlin DSL extensions - GraalVM Native Image metadata - Logstash direct streaming ## How Does Hermes Stack Up? You're probably wondering: "How does this compare to what I'm already using?" Fair question. Here's the honest breakdown: ## Getting Started Ready to give it a spin? Here's how to get Hermes into your project. ### Maven Setup ```xml path=null start=null io.github.dotbrains hermes-api 1.0.0 io.github.dotbrains hermes-processor 1.0.0 provided io.github.dotbrains hermes-core 1.0.0 runtime org.apache.maven.plugins maven-compiler-plugin io.github.dotbrains hermes-processor 1.0.0 ``` ### Spring Boot Quick Start **1. Add the starter dependency:** ```xml path=null start=null io.github.dotbrains hermes-spring-boot-starter 1.0.0 ``` **2. Configure in `application.yml`:** ```yaml path=null start=null hermes: level: root: INFO packages: com.example: DEBUG async: enabled: true queue-size: 2048 ``` **3. Use in your code:** ```java path=null start=null @InjectLogger @Service public class UserService extends UserServiceHermesLogger { public void createUser(String username) { log.info("Creating user: {}", username); } } ``` ## Tech Stack **Core Technologies:** - Java 17 (Records, Text Blocks, Modern JVM) - LMAX Disruptor (Lock-free async processing) - ServiceLoader SPI (Decoupled architecture) - Annotation Processing (Compile-time code generation) **Integration & Frameworks:** - Spring Boot (Auto-configuration) - Kotlin (DSL extensions) - Maven/Gradle (Build system) - GraalVM (Native image compilation) **Testing & Quality:** - JUnit 5 (Unit testing) - Mockito (Mocking framework) - GitHub Actions (CI/CD) - Maven Central (Artifact distribution) ## The Bottom Line Hermes brings Java logging into the modern era. By leveraging Java 17 features, LMAX Disruptor, and compile-time code generation, it delivers the performance you need without the boilerplate you hate. Whether you're building microservices that need to log millions of events per second, data pipelines processing Kafka streams, or enterprise Spring Boot apps, Hermes has your back. Fast, flexible, and actually enjoyable to use—that's the goal. Want to learn more? Check out the [official docs](https://dotbrains.github.io/hermes) or dive into the [GitHub repo](https://github.com/dotbrains/hermes). And yes, contributions are welcome!

Projects

Pinned Projects

🧙🏼 Transmute Core Game Engine

⚡ Hermes Logging Library for Java

🛠️ You Build It: Interactive Coding Challenges Platform

☁️ Cloud Tools

Jan 11, 2026

Jan 10, 2026

Jan 10, 2026

Dec 10, 2025

Sep 19, 2025

Sep 14, 2025

Open SourceYou can find all of my projects on my GitHub.

Open Source
You can find all of my projects on my GitHub.