Repository navigation
Releases
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
v1.2
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
Throwablethat no{}placeholder consumes becomes the exception of the entry, soLOG.error("Failed", e)andLOG.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, andConsoleLogger.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.
ConsoleLoggerreadsnanolog.level, per-package or per-class rules (nanolog.level.com.acme.payments=DEBUG,nanolog.levels) and thenanolog.console.*display options. A package rule beats the global level, even one set in code. - Environment variables. Every setting,
nanolog.loggerandnanolog.configincluded, can be set as an environment variable (NANOLOG_LEVEL,NANOLOG_LOGGER). Precedence:-D, environment,nanolog.properties. JsonLogger. One JSON object per line withts,level,logger,thread,message,template,args,callerandexception, selectable with-Dnanolog.logger=com.nanolaba.logging.JsonLogger.LogEntry.getTimestamp()andLogEntry.getThreadName()record when and where an entry was created.MemoryLoggerandCompositeLogger.try (MemoryLogger log = MemoryLogger.install()) { ... }captures entries in a test and puts the previous logger back afterwards;CompositeLoggersends 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 calledLOGin%file:%lineand%l, instead ofSlf4jLogger.log.ConsoleLogger: a throwable whosetoString()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.txtand the agent skillskills/nanolog/SKILL.mdgive 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
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)andLOG.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 canrequires 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 thenanolog.prefix are copied into system properties; other keys are ignored, so the file can no longer alter unrelated JVM settings.Slf4jLogger: anullsource class goes to theROOTlogger instead of throwing; an entry without a message no longer logs the wordnull.ConsoleLogger: timestamp formatting is thread-safe.LogEntry: a brokentoString()inside anObject[]argument no longer propagates to the caller; only that element is rendered as[FAILED toString()].- A
nullcontext 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