Skip to content
parvez3019Public

About

Fingers-crossed logging for Java: buffer INFO/DEBUG per request, flush only on error. Full debug context, a fraction of the log volume. SLF4J · Spring Boot · Java 17

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

8 stars

Watchers

1 watching

Forks

log4error

Fingers-crossed logging for Java: keep INFO/DEBUG context for failed requests, write nothing for successful ones.

Maven Central CI Docs javadoc Java 17+ License Stars

Docs site · 5-minute demo · Spring Boot guide · FAQ · AI prompt · Contributing


Teams turn INFO logging off in production to cut cost and noise. Then a request fails, and all that's left is one ERROR line and a stack trace.

log4error buffers each request's INFO/DEBUG lines in memory. Successful requests write nothing. When a request fails, the whole trail is written next to the error, tagged with the request ID. It works through SLF4J with any backend, and ships a Spring Boot starter.

RequestLogger.get().info("Fetching order {}", id);                  // buffered
RequestLogger.get().debug("Cache miss for customer profile");       // buffered
RequestLogger.get().info("Calling payment provider for order {}", id);
...
RequestLogger.get().error("Payment failed for order {}", id, ex);   // flush + error
10:33:15.376 INFO  [req-9b21] Fetching order 8812
10:33:15.376 DEBUG [req-9b21] Cache miss for customer profile
10:33:15.376 INFO  [req-9b21] Calling payment provider for order 8812
10:33:15.376 ERROR [req-9b21] Payment failed for order 8812
java.lang.IllegalStateException: card declined (code 51)

A successful request writes none of those lines. A failed one writes all of them.

Why log4error?

  • 🔇 Quiet happy path: successful requests write zero buffered lines, so you don't pay ingestion or storage for them.
  • 🔎 Full context on failure: every INFO/DEBUG line from the failed request, in order, next to the error.
  • 🏷️ Request IDs built in: read from x-request-id (or generated) and put in the MDC for every line.
  • ⚡ About 250× cheaper than writing: buffering costs ~5 ns per line (benchmarks).
  • 🌱 Spring Boot starter: one dependency, auto-configured filter, log4error.* properties.
  • 🪶 Tiny core: a single dependency, slf4j-api. Works with Logback, Log4j2 or JUL.
  • 🛡️ Bounded memory: capped per request (500 events by default); the oldest are dropped first.
  • 🤖 AI-ready: a paste-ready prompt for Claude Code, Cursor or Copilot to integrate log4error and migrate your log calls.

See when to use it and how it compares with sampling, runtime log levels and APM breadcrumbs.

Quickstart

Try it (5 minutes). You need Java 17+ and Maven.

git clone https://github.com/parvez3019/log4error.git
cd log4error
make demo
# in another terminal:
curl localhost:8080/orders/1      # succeeds: nothing is logged
curl localhost:8080/orders/fail   # fails: the full trail is logged

Add it to your Spring Boot service:

<dependency>
    <groupId>io.github.parvez3019</groupId>
    <artifactId>log4error-spring-boot-starter</artifactId>
    <version>0.2.0</version> <!-- see the Maven Central badge for the latest -->
</dependency>
# application.yml
logging:
  level:
    root: WARN                    # your normal production level
    io.github.parvez3019: DEBUG   # required: let flushed lines through
  pattern:
    console: "%d{HH:mm:ss.SSS} %-5level [%X{x-request-id:-}] %logger{20} - %msg%n"

Then log through RequestLogger.get() and call .error(...) where you handle failures. The logging.level line is required: flushed lines go through your backend's level filter, so without it a failed request prints only the ERROR. The Spring Boot guide covers every property, error handlers, background threads and testing.

Not on Spring Boot? Add io.github.parvez3019:log4error:0.2.0 and copy the request filter example. See How it works.

Documentation

The full docs are published at parvez3019.github.io/log4error, and are also readable here on GitHub:

Topic
Spring Boot starter: properties, error handlers, background threads, testing docs/spring-boot.md
How it works: lifecycle, flush semantics, timestamps, memory, threading docs/how-it-works.md
Troubleshooting & FAQ docs/troubleshooting.md
When to use it, alternatives, prior art docs/comparison.md
Benchmarks docs/performance.md
Upgrading (0.2.0, 0.1.0) and changelog docs/upgrade-0.2.0.md · docs/upgrade-0.1.0.md · CHANGELOG.md
AI prompt for coding agents docs/INTEGRATE_AND_MIGRATE_PROMPT.md

API at a glance

Method Behavior
info / debug Buffer the line (no I/O)
error Flush the buffer, write the ERROR, clear the buffer
pInfo / pDebug / pWarn / pError Write immediately (not buffered)
printInfoLogs() / clearInfoLogStack() Flush without clearing / discard
Logger.of(Class), new Logger(int) Custom logger name / buffer cap
RequestLogger.get() (starter) The current request's logger

Limits: the buffer is thread-bound, so it isn't shared with @Async, executors or WebFlux (#20, #24). Flushed lines carry the flush timestamp.

Tech stack

Category Technology
Language Java 17+
Logging API SLF4J 2.x (any backend: Logback, Log4j2, JUL)
Framework Spring Boot 3.x starter (servlet stack); plain servlet filter for everything else
Build Maven (multi-module); Gradle-friendly artifacts on Maven Central
Tests JUnit 5, Spring Boot Test, JMH benchmarks

Contributing

Issues, ideas and pull requests are welcome. Start with CONTRIBUTING.md, pick a good first issue, or share how you use it in Discussions. If log4error saves you log volume or debugging time, a ⭐ helps other teams find it.

License

Apache License 2.0

About

Fingers-crossed logging for Java: buffer INFO/DEBUG per request, flush only on error. Full debug context, a fraction of the log volume. SLF4J · Spring Boot · Java 17

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

8 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages