1 files changed, 119 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0424e00
--- /dev/null
+++ b/README.md
@@ -0,0 +1,119 @@
+# Log4j2 Benchmark Tool
+
+A minimal Java tool to benchmark Log4j2 logging throughput with configurable concurrent threads and various logging configurations.
+
+## Features
+
+- Configurable number of concurrent logging threads
+- Duration-based or event-count-based test modes
+- Configurable message size (~100 chars default)
+- Multiple Log4j2 configurations to compare:
+  - `sync-immediate` - Synchronous with immediateFlush=true
+  - `sync-buffered` - Synchronous with immediateFlush=false (8KB buffer)
+  - `async-1k` - AsyncLogger with 1024 ring buffer size
+  - `async-4k` - AsyncLogger with 4096 ring buffer size
+  - `async-10k` - AsyncLogger with 10240 ring buffer size
+- CSV output support for further analysis
+
+## Requirements
+
+- Java 17+
+- Maven 3.6+
+
+## Build
+
+```bash
+mvn clean package
+```
+
+This creates an executable fat JAR at `target/log4jbench-1.0-SNAPSHOT.jar` (~2.7MB).
+
+## Usage
+
+### Basic Run (all configs, 100 threads, 10s duration)
+
+```bash
+# With Maven
+mvn exec:java
+
+# With standalone JAR
+java -jar target/log4jbench-1.0-SNAPSHOT.jar
+```
+
+### With Custom Options
+
+```bash
+java -jar target/log4jbench-1.0-SNAPSHOT.jar --threads=8 --duration=30 --warmup=5
+```
+
+### Event-Count Mode
+
+```bash
+java -jar target/log4jbench-1.0-SNAPSHOT.jar --mode=events --events=500000 --threads=2
+```
+
+### Test Specific Configs Only
+
+```bash
+java -jar target/log4jbench-1.0-SNAPSHOT.jar --configs=sync-immediate,async-4k
+```
+
+### Custom Message Size
+
+```bash
+java -jar target/log4jbench-1.0-SNAPSHOT.jar --msg-size=200 --threads=4
+```
+
+### Export to CSV
+
+```bash
+java -jar target/log4jbench-1.0-SNAPSHOT.jar --output=results.csv
+```
+
+## Command Line Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-t, --threads=N` | Number of concurrent threads | 100 |
+| `-m, --mode=MODE` | Test mode: `duration` or `events` | duration |
+| `-d, --duration=N` | Test duration in seconds | 10 |
+| `-e, --events=N` | Total events (events mode) | 1000000 |
+| `-w, --warmup=N` | Warmup duration in seconds | 3 |
+| `-s, --msg-size=N` | Message size in characters | 100 |
+| `-c, --configs=LIST` | Comma-separated config names | all |
+| `-o, --output=FILE` | Output CSV file | stdout only |
+
+## Example Output
+
+```
+=== Log4j2 Benchmark ===
+Threads: 4 | Mode: DURATION | Message size: 100 chars
+Duration: 10s | Warmup: 3s
+Configs: [sync-immediate, sync-buffered, async-1k, async-4k, async-10k]
+
+Running: sync-immediate ...
+sync-immediate   |   4 threads |    1,234,567 events | 10.00s | 123,456 events/s | 12.34 MB/s
+
+Running: async-4k ...
+async-4k         |   4 threads |    5,678,901 events | 10.00s | 567,890 events/s | 56.78 MB/s
+```
+
+## Log Configurations
+
+### sync-immediate
+Standard synchronous file appender with `immediateFlush="true"`. Every log event is flushed to disk immediately.
+
+### sync-buffered
+Synchronous file appender with `immediateFlush="false"` and 8KB buffer. Events are batched before writing.
+
+### async-1k / async-4k / async-10k
+Async loggers using LMAX Disruptor with ring buffer sizes of 1024, 4096, and 10240 respectively. Logging threads hand off events to a background thread for I/O.
+
+## Notes
+
+- **Cache dropping**: Before each test, the tool attempts to drop Linux filesystem caches (`sync; echo 3 > /proc/sys/vm/drop_caches`) for consistent results. Run with `sudo` for this to work.
+- **Async loggers**: Use the LMAX Disruptor for high-throughput async logging.
+
+## License
+
+MIT