Repository navigation
v1.3
Nanolog 1.3 makes logging cheaper and safer to leave in code, and gives tests and coding agents more control over what reaches the output. The public API only grows. Every change is covered by tests under a 100% pitest mutation threshold, run on JDK 8, 11, 17 and 21, and the performance figures come from the new JMH benchmarks.
New
- Levels at run time.
LOG.setLevel(LogEntryLevel.INFO),LOG.setLevel("com.acme.payments", DEBUG),LOG.clearLevel(name)andLOG.resetLevels()change the levels while the application runs, in every thread;try (LOG.LevelOverride ignored = LOG.withLevel("com.acme", TRACE)) { ... }does it for a block or a test. A level may also be a string as in the settings,"OFF"included.ConsoleLogger,JsonLoggerandCompositeLoggerimplement the newILevelControl. - Rate limiting per call site.
LOG.once().warn(...)logs a statement the first time only,LOG.atMostEvery(10, TimeUnit.SECONDS).warn(...)at most once per period. The next entry that gets through carries the number of skipped calls, printed as[skipped 241]. - Shorter stack traces.
nanolog.exception.exclude=org.junit,jdk.internal.reflect,...collapses runs of such frames into... N frames excluded, andnanolog.exception.maxFramescaps the frames of each throwable, inConsoleLoggerand in thestackTracefield ofJsonLogger. Without them the output is exactly that ofprintStackTrace. - Assertions in tests.
MemoryLogger.assertNoneAtOrAbove(WARN),assertLogged(level, text),assertTemplateLogged(level, "Retry {} of {}")andgetEntries(SomeClass.class). A failure is a plainAssertionErrorthat lists every captured entry with its call site and stack trace. - Strict mode in tests. Every finding of
nanolog.strict=truealso reaches the installed logger through the newILogger.onDiagnostic, andMemoryLogger.assertNoDiagnostics()fails on it, even for a template that an earlier test met first. - Output stream.
nanolog.console.stream=out|err|err@LEVELchooses the stream of each level, sojava -jar app.jar | jqkeeps theERRORlines ofJsonLogger. - Thread name.
nanolog.console.showThread=trueprints[main]after the date. Off by default, so existing output keeps its format. - Disabled levels without a stack walk. A call without an explicit class at a level that is off for every class now costs about 2 ns instead of 8 to 11 µs:
LOGasks the newILogger.mayBeEnabled(level)before it looks for the caller. - Faster caller detection on Java 9+.
StackWalkerreplaces reading the stack trace of aThrowable: about 3 µs instead of 10 to 26 µs on JDK 17, and hardly more on deep stacks. A caller in any class loader is found exactly. Java 8 keeps theThrowablewalk.
Fixes
- A logger that throws no longer breaks the logging call: the failure is reported once per logger class with a
[NANOLOG]line and the entry is printed toSystem.err. InsideCompositeLoggerthe other delegates still receive it. - A lazy message whose
Supplierthrows is logged as[FAILED supplier: <exception>]instead of escaping. - A call with no qualifying caller frame (
-XX:-StackTraceInThrowable, or code running entirely inside anILogger) is logged without a source class instead of throwingIllegalStateException. - A class loader error during caller detection, such as
NoClassDefFoundErroror GraalVM'sMissingReflectionRegistrationError, no longer escapes. - A logger installed with
LOG.init(...)orMemoryLogger.install()is guaranteed to be seen by threads that are already logging. - An anonymous or local source class is printed as
[Foo$1]instead of[]or[null]. - A
[NANOLOG]diagnostic is always one line: control characters in the values it repeats are escaped, so a level passed toLOG.setLevelfrom a request cannot forge a log line.
Documentation and build
- JMH benchmarks,
mvn -P benchmark test-compile exec:exec, with results for JDK 8 to 25 insrc/jmh/RESULTS.md; the README quotes the measured costs. - README: sections on changing levels at run time, rate limiting and shorter stack traces, a title and description that say what Nanolog is, and corrected statements about MDC through
Slf4jLoggerand about whatILogger.isEnabledsaves. English and Russian. llms.txtand the agent skillskills/nanolog/SKILL.mdcover the new features, marked 1.3+.
Installation
<dependency>
<groupId>com.nanolaba</groupId>
<artifactId>nanolog</artifactId>
<version>1.3</version>
</dependency>implementation("com.nanolaba:nanolog:1.3")Requires Java 8 or later. slf4j-api is needed only when Slf4jLogger is used.
Full changelog: v1.2...v1.3