feat: performance benchmarking module + baseline (KOJAK-68)

[endrju19]

Summary

Establishes a reproducible JMH-based performance benchmarking setup and captures the pre-optimization baseline for okapi. Provides a reference point against which all subsequent optimizations (KOJAK-70..79) will be measured and documented.

KOJAK-68 — Performance benchmarking module + baseline measurement

What's included

okapi-benchmarks module

• JMH 1.37 via me.champeau.jmh Gradle plugin
• Default config: fork=2, warmup=3, iter=5 for release-quality runs
• Located in okapi-benchmarks/ (not published, like okapi-integration-tests)

Benchmarks

Class	What it measures
KafkaThroughputBenchmark	End-to-end fanout, real Postgres + real Kafka (Testcontainers), @Param batchSize ∈ {10, 50, 100}
HttpThroughputBenchmark	End-to-end fanout, real Postgres + WireMock, @Param batchSize × httpLatencyMs ∈ {0, 20, 100}
DelivererMicroBenchmark	Single-entry deliver() with MockProducer / WireMock — measures pure code overhead

Methodology touches

• @OperationsPerInvocation(1000) so JMH ms/op directly reflects per-message cost
• Scheduler is bypassed in benchmarks — we measure the processing pipeline's capacity, not polling cadence (which is a deployment-time knob)
• Per-invocation @Setup truncates outbox and re-populates fresh PENDING entries

Documentation

• benchmarks/README.md — methodology + how to run + caveats (WireMock in-JVM, localhost ≠ production)
• benchmarks/results-baseline-2026-04.md — full baseline tables with interpretation

Baseline numbers (smoke run on M3 Max, JDK 25 LTS)

Kafka

batchSize	msg/s
10	~109
50	~115
100	~115

Flat across batchSize — confirms sync producer.send().get() blocking is the bottleneck.

HTTP

batchSize	latencyMs	msg/s
10	0	~1,513
50	0	~2,717
100	0	~3,322
10	20	~33
50	20	~33
100	20	~36
10	100	~9
50	100	~9
100	100	~9

At non-zero latency, throughput is flat — proves sequential httpClient.send() blocking dominates. Library + DB ceiling visible only at latencyMs=0.

Microbenchmark

• KafkaMessageDeliverer.deliver() with MockProducer: ~1.8M ops/s — pure code overhead is negligible

How to reproduce

# Quick smoke run (~10 min)
./gradlew :okapi-benchmarks:jmhJar
java -jar okapi-benchmarks/build/libs/okapi-benchmarks-jmh.jar -f 1 -wi 1 -i 2 -w 10s -r 15s

# Full release-quality run (~30 min)
./gradlew :okapi-benchmarks:jmh

Test plan

• ./gradlew :okapi-benchmarks:jmhClasses compiles cleanly
• ./gradlew :okapi-benchmarks:ktlintCheck passes
• JMH discovers all 4 benchmarks (-l flag)
• Smoke microbenchmark run completes successfully (DelivererMicroBenchmark.kafkaDeliver)
• Smoke throughput run completes for both Kafka and HTTP transports across full @Param matrix
• Results captured in benchmarks/results-baseline-2026-04.md

Notes for reviewers

• WireMock caveat: in-JVM Jetty servlet adds ~0.3 ms overhead per request. Documented in README. Future optimization (parked in KOJAK-69 ideas backlog): swap to Square's MockWebServer for tighter measurements.
• No CI integration yet: full benchmark run is ~30 min, not suitable for PR gate. Future task: regression detection via github-action-benchmark consuming the JSON output.
• .log files are gitignored — verbose console output is not a useful artifact; structured JSON is sufficient for archival.