Nilog 1.0.4

⚡ Nilog

Zero-allocation, high-performance logging for Microsoft.Extensions.Logging

Same ILogger. Same {Named} templates. None of the garbage.

📖 Full docs, recipes, and architecture: github.com/gcfernando/Nilog

The stock ILogger extensions allocate a params object[] on every single call — even when the level is switched off and the message is thrown straight in the bin. On a hot path that is millions of pointless allocations and a busy garbage collector.

Nilog swaps that array for a stack-only struct. A disabled call allocates nothing and returns in under half a nanosecond.

using Nilog;

// 0–16 args: zero allocation when the level is disabled. 30–56% faster when it's enabled.
logger.WriteInformation("User {UserId} ordered {Count} items", userId, count);

// Up to sixteen args — still zero-array typed, no object[] ever built (extended to 16 in v1.0.4)
logger.WriteInformation("User {UserId} bought {Sku} x{Qty} in {Region} via {Channel} ({Tier}) at {Ts} ref {Ref} batch {B}",
    userId, sku, qty, region, channel, tier, ts, refId, batch);

⚡ At a glance

📊 Benchmarks

Measured with BenchmarkDotNet · .NET 10.0 · Intel Core i7-13850HX · Windows 11. ShortRun job — 3 warmup + 3 measurement iterations, Server GC. The 9-arg disabled-path figures (v1.0.4) are from Nilog.Benchmark's HighArityExtendedBenchmarks; reproduce with dotnet run -c Release --project Nilog.Benchmark -f net10.0 -- --filter "*HighArityExtended*".

🏆 Disabled-path: the zero-allocation proof

When the level is filtered off, Microsoft still builds the object[] before calling IsEnabled. Nilog checks first — and builds nothing.

─── 1-arg disabled call ──────────────────────────────────────────────────
Microsoft  ████████████████████████████████████  44.74 ns │  96 B ← always allocates
Nilog      ▏                                       0.46 ns │   0 B ← 97× faster in this benchmark

─── 5-arg disabled call (typed overload) ─────────────────────────────────
Microsoft  ████████████████████████████████████ 132.91 ns │ 224 B
Nilog      ▏                                       0.23 ns │   0 B ← 577× faster in this benchmark

─── 8-arg disabled call (typed overload — v1.0.3) ────────────────────────
Microsoft  ████████████████████████████████████ 221.03 ns │ 336 B
Nilog      ▏                                       0.82 ns │   0 B ← 268× faster in this benchmark

─── 9-arg disabled call (typed overload — NEW in v1.0.4) ─────────────────
Microsoft  ████████████████████████████████████ 211.31 ns │ 368 B
Nilog      ▏                                       0.45 ns │   0 B ← 469× faster in this benchmark

The 0 B figures are not estimates — asserted as exactly 0L allocated bytes by AllocationGateTests (including DisabledPath_NineTypedArgs_AllocatesZeroBytes added in v1.0.4) and confirmed by BenchmarkDotNet's MemoryDiagnoser.

🔥 Enabled calls — Nilog still wins

💥 Stress test — 10,000-call loop, every typed arity

The disabled path stays flat at ~2.9 μs with 0 B, no matter whether the template carries 3, 4, or 5 arguments. The enabled loop is consistently ~34–36% faster, ~24–26% less allocation than Microsoft across the same range.

⚡ Special paths

⚠️ Limitations

Nilog removes the call-site object[] allocation for common logging calls, but it does not make every logging scenario allocation-free. We list these honestly rather than overclaim.

Why some of these are by design, not bugs: Nilog is a thin, allocation-aware layer over ILogger. It deliberately does not own the sink, the transport, or the async pipeline — that is what makes it a true drop-in that works with any Microsoft.Extensions.Logging provider and any hosting/cloud platform. Allocation past the call site (string rendering, sink I/O) belongs to the formatter and sink you already chose.

🗺️ Roadmap

Status of planned work. ✅ shipped · 🚧 in progress · 🔭 considering · ⛔ decided against.

If you need something here sooner, open an issue at github.com/gcfernando/Nilog/issues.

📦 Install

dotnet add package Nilog

<PackageReference Include="Nilog" Version="1.0.4" />

Targets .NET 8.0, 9.0, and 10.0. Dependencies: Microsoft.Extensions.Logging.Abstractions and Microsoft.Extensions.ObjectPool. Native AOT / trimming friendly.

🚀 Quick start

using Microsoft.Extensions.Logging;
using Nilog; // <- that's the whole setup

ILogger logger = LoggerFactory
    .Create(b => b.AddConsole())
    .CreateLogger("App");

// Plain message — ~3.8 ns, 0 bytes
logger.WriteInformation("Service started");

// Structured, strongly-typed, zero array allocation (1–16 args)
logger.WriteInformation("User {UserId} signed in from {Ip}", 42, "10.0.0.1");

// Up to sixteen args — 6–16 source-generated in v1.0.4, zero array, zero boxing on disabled path
logger.WriteInformation("User {UserId} bought {Sku} x{Qty} in {Region} via {Channel} ({Tier})",
    userId, sku, qty, region, channel, tier);

// Exception with typed context — no array, no boxing
try { Risky(); }
catch (Exception ex)
{
    logger.WriteError("Checkout failed for cart {CartId}", ex, cartId);
}

🆚 Nilog vs the alternatives

Every row is phrased so ✅ is always the good result (✅ yes/good · ❌ no · ➖ partial).

🧭 Choosing the right method

Tip: Keep templates to ≤ 16 named holes to stay on the zero-array typed path.

✨ Features

Six levels, typed for 0–16 args, params for 17+

logger.WriteTrace("Polling queue, {Count} items", count);
logger.WriteDebug("Cache miss for key {Key}", key);
logger.WriteInformation("Order {OrderId} confirmed", orderId);
logger.WriteWarning("Retry {Attempt}/{Max} for {Job}", attempt, max, job);
logger.WriteError("Payment failed for {OrderId}", ex, orderId);
logger.WriteCritical("Database unreachable on {Host}", ex, host);

// Nine-arg typed (NEW in v1.0.4) — zero array, 0.45 ns / 0 B on disabled path
logger.WriteInformation("{A} {B} {C} {D} {E} {F} {G} {H} {I}", a, b, c, d, e, f, g, h, i);

// Up to sixteen args — all zero-array on the disabled path
logger.WriteInformation("User {UserId} bought {Sku} x{Qty} in {Region} via {Channel} ({Tier}) ref {Ref} at {Ts}",
    userId, sku, qty, region, channel, tier, refId, ts);

Runtime-level API — zero alloc for 0–16 typed args

LogLevel level = config.Verbose ? LogLevel.Debug : LogLevel.Information;
Nilogger.Log(logger, level, "Processing {JobId}", jobId);                       // ~4 ns, 0 B
Nilogger.Log(logger, level, "{A} {B} {C} {D} {E} {F} {G} {H} {I}", a, b, c, d, e, f, g, h, i); // still 0 B when disabled

Bounded template cache

// Prevent unbounded memory growth from interpolated templates
Nilogger.MaxTemplateCacheEntries = 10_000;  // default; new entries parsed but not cached beyond limit

🔍 Static analysis — catch the structured-logging footguns at compile time

Every optimization above depends on the message argument being a stable string literal whose placeholders match its arguments. A few mistakes undo it all silently:

logger.WriteInformation($"User {id} signed in");  // compiles fine, silently undoes everything
logger.WriteInformation("{A} {B}", a);            // 2 holes, 1 arg → renders raw, loses props
logger.WriteInformation("User " + id + " in");    // concatenation → never a stable template

Nilog.Analyzers is a separate, opt-in package (not referenced by Nilog.Core) that catches all three at build time across every Nilog call shape:

<PackageReference Include="Nilog.Analyzers" Version="1.0.4" PrivateAssets="all" />

logger.WriteInformation($"User {id} signed in");        // ❌ NILOG001 (+ one-click fix)
logger.WriteInformation("{A} {B}", a);                  // ❌ NILOG002 (2 placeholders, 1 arg)
logger.WriteInformation("User " + id + " in");          // ❌ NILOG003
logger.WriteInformation("{Id} retried {Id}", a, b);     // ❌ NILOG004 (duplicate {Id})
logger.WriteInformation("{0} {1}", a, b);               // 🔵 NILOG005 (prefer named)
logger.WriteInformation("Failed {Error}", ex);          // ❌ NILOG006 (use the exception parameter)
logger.WriteInformation("Unclosed {Brace");             // ❌ NILOG007 (malformed)
logger.WriteInformation("User {userId}", id);           // 🔵 NILOG008 (PascalCase)

logger.WriteInformation("User {UserId} signed in", id); // ✅ no diagnostic

Promote the correctness rules to build-breaking errors in CI (NILOG005/008 are Info-only style):

<WarningsAsErrors>$(WarningsAsErrors);NILOG001;NILOG002;NILOG003;NILOG004;NILOG006;NILOG007</WarningsAsErrors>

Or via .editorconfig for the whole repo: dotnet_diagnostic.NILOG001.severity = error.

It's syntax/semantics-based — it catches the mistake at the call site. Full details: Static analysis.

FlushAsync — real flush for buffering sinks

// A batching/buffering sink registers how to drain itself…
Nilogger.RegisterFlush(ct => myBatchingSink.FlushAsync(ct));

// …and shutdown awaits every registered sink. With nothing registered this is a
// zero-allocation no-op (returns Task.CompletedTask synchronously).
await Nilogger.FlushAsync(cancellationToken);

// Typed multi-pair scopes — no dictionary allocation, no array copy (NEW in v1.0.4)
using (logger.WriteScope("OrderId", orderId, "CustomerId", customerId, "Currency", "GBP"))
{
    logger.WriteInformation("Order opened");   // all three KVPs in scope
}

🏭 Production readiness

📖 API at a glance

// Extension methods on ILogger — Write* for all six levels (typed 0–16, params 17+)
void WriteInformation(this ILogger logger, string message, params object[] args);
void WriteInformation<T0>(this ILogger logger, string message, T0 arg0);
void WriteInformation<T0,T1>(this ILogger logger, string message, T0 arg0, T1 arg1);
void WriteInformation<T0,T1,T2>(this ILogger logger, string message, T0 arg0, T1 arg1, T2 arg2);
void WriteInformation<T0,T1,T2,T3>(this ILogger logger, string message, T0 arg0, T1 arg1, T2 arg2, T3 arg3);
void WriteInformation<T0,T1,T2,T3,T4>(this ILogger logger, string message, T0 arg0, T1 arg1, T2 arg2, T3 arg3, T4 arg4);
// …and 6–16-argument overloads source-generated by Nilog.SourceGenerators (extended to 16 in v1.0.4)
void WriteInformation<T0,…,T15>(this ILogger logger, string message, T0 arg0, …, T15 arg15);
// Identical shape for WriteTrace, WriteDebug, WriteWarning

// Error/Critical — without exception (typed, zero-array; 1–16 args)
void WriteError<T0,…,T15>(this ILogger logger, string message, T0 arg0, …, T15 arg15);
// With exception
void WriteError<T0,…,T15>(this ILogger logger, string message, Exception exception, T0 arg0, …, T15 arg15);
// Identical shape for WriteCritical

// Exception reports
void WriteErrorException(this ILogger logger, Exception ex,
    string title = "System Error", bool moreDetailsEnabled = false);  // basic: < 300 B (v1.0.4)

// Scopes — typed multi-pair overloads NEW in v1.0.4 (no dictionary, no array)
IDisposable WriteScope(this ILogger logger, string key, object value);
IDisposable WriteScope<T1,T2>       (this ILogger logger, string k1, T1 v1, string k2, T2 v2);
IDisposable WriteScope<T1,T2,T3>    (this ILogger logger, string k1, T1 v1, string k2, T2 v2, string k3, T3 v3);
IDisposable WriteScope<T1,T2,T3,T4> (this ILogger logger, string k1, T1 v1, string k2, T2 v2, string k3, T3 v3, string k4, T4 v4);
IDisposable WriteScope(this ILogger logger, IDictionary<string, object> context);

// Static runtime-level API (zero-array for 0–16 typed args)
void Nilogger.Log<T0,…,T15>(ILogger logger, LogLevel level, string message, T0 a, …, T15 p);

// Global settings
static int MaxTemplateCacheEntries { get; set; }            // default 10,000
static void ShutdownUtcTimer();

// Flush: real drain of registered buffering sinks (no-op when none registered)
static void RegisterFlush(Func<CancellationToken, Task> flush);
static bool UnregisterFlush(Func<CancellationToken, Task> flush);
static Task FlushAsync(CancellationToken token = default);

❓ FAQ

Is it really zero allocation? On the disabled path: yes — 0 bytes for 0–16 typed args (extended to 16 in v1.0.4; asserted by the test suite including DisabledPath_NineTypedArgs_AllocatesZeroBytes). On the enabled path Nilog still allocates the rendered string but avoids the object[] for all 1–16 typed args — 25–32% less than the framework for 1–8 args, 37% faster at 9 args.

What about 9+ arguments? Typed overloads now reach sixteen (1–5 hand-written, 6–16 source-generated). A 9-arg disabled call allocates 0 B and runs in 0.45 ns (469× faster than Microsoft). Only at 17+ args does Nilog fall back to params object[] — the same as the framework. Prefer ≤ 16 named holes on hot paths, or move extra context into a typed WriteScope (2–4 pairs) or dictionary scope.

Does it work with my logging engine / sink / cloud platform? Yes. Nilog only produces standard Microsoft.Extensions.Logging state (IReadOnlyList<KVP> + {OriginalFormat}), so it flows through any MEL provider — Console, Serilog, NLog, OpenTelemetry, Seq, Application Insights, AWS/GCP exporters — and runs anywhere .NET runs (containers, Azure Functions, AWS Lambda, Kubernetes). It adds no transport of its own, so there is nothing platform-specific to configure. This is verified, not asserted: LoggingEngineInteropTests runs Nilog through the real LoggerFactory + ILoggerProvider pipeline (the exact contract every engine integrates through) and checks the rendered message, {OriginalFormat}, named properties, exceptions, and level-filtering all arrive intact.

Is it AOT / trimming safe? Yes — generics, pooling, string.Format, stack-allocated spans; no reflection. Native AOT friendly.

What does Nilog.Analyzers check? Eight rules, full parity with SerilogAnalyzer: NILOG001 (interpolated templates, with a one-click code fix), NILOG002 (placeholder/argument count mismatch), NILOG003 (concatenated or string.Format templates), NILOG004 (duplicate named placeholder), NILOG005 (positional placeholders, Info), NILOG006 (an exception passed as a template value), NILOG007 (malformed template), and NILOG008 (non-PascalCase placeholder name, Info) — across every Write*/Nilogger.Log call shape. It's a separate, opt-in package — not referenced by Nilog.Core — so installing Nilog never pulls it in automatically.

📄 License

MIT © Gehan Fernando. Full docs at github.com/gcfernando/Nilog.