Logsmith 0.6.0

Logsmith

Zero-allocation, source-generated structured logging for .NET 10.

Logsmith is a logging framework where the source generator is the framework. Every log method is analyzed at compile time, and the generator emits fully specialized, zero-allocation UTF8 code tailored to your exact parameters. No reflection. No boxing. No runtime parsing of message templates.

Documentation | API Reference

Packages

Name	NuGet	Description
Logsmith		Runtime library with public types, sinks, and the bundled source generator. Default mode: Shared.
Logsmith.Generator		Thin meta-package. Depends on Logsmith for the generator and build assets only — no runtime DLL. Default mode: Standalone.
Logsmith.Extensions.Logging		Microsoft.Extensions.Logging bridge. Routes ILogger calls through Logsmith sinks.

Why Logsmith

Most .NET logging frameworks parse message templates at runtime, box value-type arguments into object[], and dispatch through multiple abstraction layers before bytes reach an output target. For applications where logging sits on the hot path — game engines, trading systems, NativeAOT deployments — those costs are measurable.

Logsmith takes the source-generator approach to its conclusion: the generator does not supplement a runtime framework, it replaces it entirely. It reads your method declarations at build time, knows the concrete types of every parameter, and emits direct UTF8 formatting calls with pre-computed property names and type-specific serialization paths.

Comparison with Other Frameworks

Features

• Zero-allocation logging pipeline — every log call writes directly to sinks with no heap allocation, no boxing, no string interpolation
• Source-generated method bodies — the generator emits fully specialized UTF8 code per log method at compile time
• Compile-time level stripping — [Conditional] attributes remove log calls below a configured threshold from release builds
• Three operating modes — Shared, Standalone, or Abstraction for apps and libraries
• Six built-in sinks — Console, File, Stream, Debug, Recording, and Null with category filtering
• Structured JSON output — IStructuredLogSink receives typed properties via Utf8JsonWriter
• Scoped context enrichment — attach ambient properties via LogScope.Push with zero overhead when inactive
• Log sampling and rate limiting — throttle high-frequency log methods with compile-time guards
• Dynamic level switching — adjust log levels at runtime via environment variables or config files
• MEL bridge — route ILogger calls through Logsmith sinks with Logsmith.Extensions.Logging
• Custom type serialization — implement IUtf8SpanFormattable and ILogStructurable for optimal formatting
• Compile-time diagnostics — template mismatches, missing parameters, and unsupported types caught before runtime

Quick Start

// 1. Initialize at startup
LogManager.Initialize(config =>
{
    config.MinimumLevel = LogLevel.Debug;
    config.AddConsoleSink();
    config.AddFileSink("logs/app.log", rollingInterval: RollingInterval.Daily);
});

// 2. Declare log methods
[LogCategory("Renderer")]
public static partial class RenderLog
{
    [LogMessage(LogLevel.Debug, "Draw call {drawCallId} completed in {elapsedMs}ms")]
    public static partial void DrawCallCompleted(int drawCallId, double elapsedMs);

    [LogMessage(LogLevel.Error, "Shader compilation failed: {shaderName}")]
    public static partial void ShaderFailed(string shaderName, Exception ex);
}

// 3. Call them
RenderLog.DrawCallCompleted(42, 1.23);

The generator emits fully specialized, zero-allocation UTF8 code for each log method at compile time. See Getting Started for the full walkthrough.

Benchmarks

Full benchmark results comparing Logsmith against MEL, Serilog, NLog, and ZLogger are available in docs/benchmarks.md.

License

This project is licensed under the MIT License.