Skip to content

Releases

v1.3

Choose a tag to compare

@andriishin andriishin released this 16 Nov 23:58

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

v1.2

Choose a tag to compare

@andriishin andriishin released this 11 Nov 01:09

Nanolog 1.2 makes the library easier to use and to debug in agent-driven development, where a coding agent edits, runs and reads the output in a short loop. The public API only grows, and every change below is covered by tests under a 100% pitest mutation threshold.

New

  • SLF4J argument order. A trailing Throwable that no {} placeholder consumes becomes the exception of the entry, so LOG.error("Failed", e) and LOG.error("Failed {}", id, e) log the stack trace. Before, the exception was silently dropped as an unused argument.
  • Call site. LogEntry.getCaller() returns the frame of the logging call, and ConsoleLogger.setShowLocation(true) prints it as [PaymentService.charge(PaymentService.java:87)], a link in IDEs and terminals. It comes from the stack walk that already detects the source class, so it costs nothing extra.
  • Levels and options without code. ConsoleLogger reads nanolog.level, per-package or per-class rules (nanolog.level.com.acme.payments=DEBUG, nanolog.levels) and the nanolog.console.* display options. A package rule beats the global level, even one set in code.
  • Environment variables. Every setting, nanolog.logger and nanolog.config included, can be set as an environment variable (NANOLOG_LEVEL, NANOLOG_LOGGER). Precedence: -D, environment, nanolog.properties.
  • JsonLogger. One JSON object per line with ts, level, logger, thread, message, template, args, caller and exception, selectable with -Dnanolog.logger=com.nanolaba.logging.JsonLogger. LogEntry.getTimestamp() and LogEntry.getThreadName() record when and where an entry was created.
  • MemoryLogger and CompositeLogger. try (MemoryLogger log = MemoryLogger.install()) { ... } captures entries in a test and puts the previous logger back afterwards; CompositeLogger sends entries to several loggers.
  • nanolog.strict=true. Reports calls whose {} placeholders and arguments do not match, once per template and with the call site. Meant for test runs.

Fixes

  • Slf4jLogger: Logback, Log4j 2 and other location-aware backends report the code that called LOG in %file:%line and %l, instead of Slf4jLogger.log.
  • ConsoleLogger: a throwable whose toString() throws no longer escapes from the logging call; it is printed as [FAILED printStackTrace()].

Documentation and build

  • Javadoc for the whole public API; the build fails on a missing comment.
  • llms.txt and the agent skill skills/nanolog/SKILL.md give coding agents the rules of the library. Both are generated together with the README and checked for drift in CI.
  • README: a new section on agent-driven development, in English and Russian.

Installation

<dependency>
    <groupId>com.nanolaba</groupId>
    <artifactId>nanolog</artifactId>
    <version>1.2</version>
</dependency>
implementation("com.nanolaba:nanolog:1.2")

Requires Java 8 or later. slf4j-api is needed only when Slf4jLogger is used.

Full changelog: v1.1...v1.2

v1.1

Choose a tag to compare

@andriishin andriishin released this 10 Nov 20:11

Nanolog 1.1 is a compatibility and robustness release: the public API only grows, and every change below is covered by tests under a 100% pitest mutation threshold.

New

  • Overloads LOG.info(throwable, "... {} ...", args) and LOG.info(sourceClass, throwable, "... {} ...", args) for every level (trace, debug, info, warn, error): log an exception together with a parameterized message in one call.
  • The jar declares Automatic-Module-Name: com.nanolaba.nanolog, so modular applications can requires com.nanolaba.nanolog;.

Fixes

  • Caller detection resolves classes through the thread's context class loader first and skips frames it cannot see, instead of failing in application servers and plugin frameworks where Nanolog lives in a parent class loader.
  • nanolog.properties: only keys with the nanolog. prefix are copied into system properties; other keys are ignored, so the file can no longer alter unrelated JVM settings.
  • Slf4jLogger: a null source class goes to the ROOT logger instead of throwing; an entry without a message no longer logs the word null.
  • ConsoleLogger: timestamp formatting is thread-safe.
  • LogEntry: a broken toString() inside an Object[] argument no longer propagates to the caller; only that element is rendered as [FAILED toString()].
  • A null context class loader at startup is tolerated.
  • The diagnostic for a missing configuration file names the right property (nanolog.config).

Documentation and build

  • README rewritten around the real usage flow (English and Russian); code samples are imported from compiled sources, so they cannot go stale.
  • CI actions are pinned to commit SHAs with a read-only token, and the generated README is checked for drift on every build.

Installation

<dependency>
    <groupId>com.nanolaba</groupId>
    <artifactId>nanolog</artifactId>
    <version>1.1</version>
</dependency>
implementation("com.nanolaba:nanolog:1.1")

Requires Java 8 or later. slf4j-api is needed only when Slf4jLogger is used.

Full changelog: v1.0...v1.1

v1.0

Choose a tag to compare

@andriishin andriishin released this 06 Jul 17:03
documentation update