Skip to content

v1.3

Choose a tag to compare

@andriishin andriishin released this 16 Nov 23:58
· 74 commits to main since this release

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) and LOG.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, JsonLogger and CompositeLogger implement the new ILevelControl.
  • 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, and nanolog.exception.maxFrames caps the frames of each throwable, in ConsoleLogger and in the stackTrace field of JsonLogger. Without them the output is exactly that of printStackTrace.
  • Assertions in tests. MemoryLogger.assertNoneAtOrAbove(WARN), assertLogged(level, text), assertTemplateLogged(level, "Retry {} of {}") and getEntries(SomeClass.class). A failure is a plain AssertionError that lists every captured entry with its call site and stack trace.
  • Strict mode in tests. Every finding of nanolog.strict=true also reaches the installed logger through the new ILogger.onDiagnostic, and MemoryLogger.assertNoDiagnostics() fails on it, even for a template that an earlier test met first.
  • Output stream. nanolog.console.stream=out|err|err@LEVEL chooses the stream of each level, so java -jar app.jar | jq keeps the ERROR lines of JsonLogger.
  • Thread name. nanolog.console.showThread=true prints [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: LOG asks the new ILogger.mayBeEnabled(level) before it looks for the caller.
  • Faster caller detection on Java 9+. StackWalker replaces reading the stack trace of a Throwable: 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 the Throwable walk.

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 to System.err. Inside CompositeLogger the other delegates still receive it.
  • A lazy message whose Supplier throws is logged as [FAILED supplier: <exception>] instead of escaping.
  • A call with no qualifying caller frame (-XX:-StackTraceInThrowable, or code running entirely inside an ILogger) is logged without a source class instead of throwing IllegalStateException.
  • A class loader error during caller detection, such as NoClassDefFoundError or GraalVM's MissingReflectionRegistrationError, no longer escapes.
  • A logger installed with LOG.init(...) or MemoryLogger.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 to LOG.setLevel from 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 in src/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 Slf4jLogger and about what ILogger.isEnabled saves. English and Russian.
  • llms.txt and the agent skill skills/nanolog/SKILL.md cover 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