👁 Image
CSharpEssentials.LoggerHelper 5.1.0

CSharpEssentials.LoggerHelper

Route Serilog sinks by log level — zero boilerplate, native ILogger<T> support.

Install the NuGet, add 5 lines of JSON, and every ILogger<T> in your app automatically routes logs to Console, File, Email, Telegram, PostgreSQL, SQL Server, Elasticsearch, and Seq — each sink receiving only the levels you want.

dotnet add package CSharpEssentials.LoggerHelper
dotnet add package CSharpEssentials.LoggerHelper.Sink.Console
dotnet add package CSharpEssentials.LoggerHelper.Sink.File
dotnet add package CSharpEssentials.LoggerHelper.Sink.Email # add only what you need

Why LoggerHelper?

Quick Start — 30 seconds

Option A — JSON config (recommended)

Program.cs

builder.Services.AddLoggerHelper(builder.Configuration);
app.UseLoggerHelper();

appsettings.LoggerHelper.json

{
 "LoggerHelper": {
 "ApplicationName": "MyApp",
 "Routes": [
 { "Sink": "Console", "Levels": ["Information", "Warning"] },
 { "Sink": "File", "Levels": ["Information", "Warning", "Error", "Fatal"] },
 { "Sink": "Email", "Levels": ["Error", "Fatal"] }
 ],
 "Sinks": {
 "File": { "Path": "C:\\Logs\\MyApp", "RollingInterval": "Day" },
 "Email": { "To": "ops@example.com", "Host": "smtp.example.com", "Port": 587 }
 },
 "General": { "EnableRequestResponseLogging": true }
 }
}

That's it. Every ILogger<T> in your app now routes through LoggerHelper.

Option B — Fluent API

builder.Services.AddLoggerHelper(b => b
 .WithApplicationName("MyApp")
 .AddRoute("Console", LogEventLevel.Information, LogEventLevel.Warning)
 .AddRoute("File", LogEventLevel.Information, LogEventLevel.Warning, LogEventLevel.Error, LogEventLevel.Fatal)
 .AddRoute("Email", LogEventLevel.Error, LogEventLevel.Fatal)
 .ConfigureFile(f => { f.Path = "C:\\Logs\\MyApp"; f.RollingInterval = "Day"; })
 .EnableRequestResponseLogging()
);

Option C — JSON base + fluent overrides (merge)

// JSON defines shared config across environments.
// Fluent adds Development-only extras without touching JSON.
builder.Services.AddLoggerHelper(builder.Configuration, b => b
 .AddRoute("Console", LogEventLevel.Debug) // extra sink only in code
);

Option D — Via ILoggingBuilder (respects Logging:LogLevel filters)

builder.Logging.ClearProviders();
builder.Logging.AddLoggerHelper(builder.Configuration);

Zero code changes for existing apps

If your app already uses ILogger<T>, you change nothing. LoggerHelper plugs in as a standard ILoggerProvider:

// Your existing service — not a single line changes
public class OrderService(ILogger<OrderService> logger) {
 public void Process(int orderId) {
 logger.LogInformation("Processing order {OrderId}", orderId); // → Console + File
 logger.LogError("Payment failed for {OrderId}", orderId); // → File + Email
 }
}

Named parameters like {OrderId} are preserved as structured Serilog properties — not flattened into strings.

BeginScope — context that travels with your logs

Add business properties once. Every log in that block carries them automatically, including logs inside methods you call:

using (_logger.BeginScope(new Dictionary<string, object?> {
 ["OrderId"] = orderId,
 ["UserId"] = userId
}))
{
 _logger.LogInformation("Validation started"); // OrderId + UserId are here
 await ValidateStock(); // logs inside also carry them
 _logger.LogInformation("Order confirmed"); // OrderId + UserId are here
}
// Outside the using: properties removed automatically

Scope nesting — properties accumulate layer by layer:

using (_logger.BeginScope(new Dictionary<string, object?> { ["OrderId"] = 123 }))
{
 using (_logger.BeginScope(new Dictionary<string, object?> { ["Provider"] = "Stripe" }))
 {
 _logger.LogInformation("Charging card");
 // OrderId=123, Provider="Stripe"
 }
 _logger.LogInformation("Order complete");
 // OrderId=123 (Provider removed)
}

Automatic enrichment on every log

Without any extra code, every log event carries:

Available sinks

Each sink is a separate NuGet — install only what you need:

Sinks self-register via a plugin mechanism — the core package has zero dependency on them.

Sensitive data masking — New in 5.0.8

Redact PII and secrets from every sink at once, declaratively:

"SensitiveDataMasking": {
 "Enabled": true,
 "Presets": [ "Email", "CreditCard", "JwtToken", "BearerToken", "ConnectionStringSecret" ],
 "SensitiveProperties": [ "Password", "ApiKey" ],
 "Rules": [ { "Name": "OrderId", "Pattern": "ORD-\\d+" } ]
}

logger.LogInformation("Login for {Email} with {Password}", "alice@example.com", "Sup3rSecret!");
// → Login for ***MASKED*** with ***MASKED***

Disabled by default — zero overhead unless enabled. Or via fluent API: .EnableSensitiveDataMasking(o => o.Presets.Add("Email")).

Per-level routing — real-world example

"Routes": [
 { "Sink": "Console", "Levels": ["Debug", "Information", "Warning"] },
 { "Sink": "File", "Levels": ["Information", "Warning", "Error", "Fatal"] },
 { "Sink": "Telegram", "Levels": ["Error", "Fatal"] },
 { "Sink": "Email", "Levels": ["Fatal"] },
 { "Sink": "Elasticsearch", "Levels": ["Information", "Warning", "Error", "Fatal"] }
]

• Developers see everything on Console during development
• File captures all non-debug logs for auditing
• Telegram pings the team on every error
• Email sends a full report only for fatal crashes
• Elasticsearch indexes everything for Kibana dashboards

Migrating from v2/v4 (legacy JSON)

See for feature parity details.

Benchmarks

See for LoggerHelper v5 vs Serilog vs NLog comparisons.

Environment-aware configuration

LoggerHelper automatically picks the right file based on the current environment:

Internal diagnostics

If a sink fails to configure (wrong connection string, unreachable SMTP server), LoggerHelper captures the error silently and exposes it — your app keeps running:

app.MapGet("/health/logging", (ILogErrorStore errors) =>
 errors.Count == 0
 ? Results.Ok("All sinks healthy")
 : Results.Problem(string.Join("\n", errors.GetAll().Select(e => $"{e.SinkName}: {e.ErrorMessage}")))
);

Request / Response logging middleware

Enable HTTP request/response logging with a single setting:

"General": { "EnableRequestResponseLogging": true }

Then activate in the pipeline:

app.UseLoggerHelper();

Building a custom sink

1. Create a project CSharpEssentials.LoggerHelper.Sink.MyTarget
2. Implement ISinkPlugin:

internal sealed class MyTargetSinkPlugin : ISinkPlugin {
 public bool CanHandle(string sinkName) =>
 sinkName.Equals("MyTarget", StringComparison.OrdinalIgnoreCase);

 public void Configure(LoggerConfiguration loggerConfig, SinkRouting routing, LoggerHelperOptions options) {
 var opts = options.GetSinkConfig<MyTargetOptions>("MyTarget")
 ?? options.BindSinkSection<MyTargetOptions>("MyTarget")
 ?? new MyTargetOptions();

 loggerConfig.WriteTo.Conditional(
 evt => routing.Matches(evt.Level),
 wt => wt.MySink(opts.ConnectionString)
 );
 }
}

public static class PluginInitializer {
 [ModuleInitializer]
 public static void Init() => SinkPluginRegistry.Register(new MyTargetSinkPlugin());
}

3. Reference CSharpEssentials.LoggerHelper as a NuGet — not a project reference.
4. The sink auto-registers at startup with no changes to the core.

Performance

LoggerHelper v5 is built on Serilog, adding a thin MEL-compatible routing layer. Overhead vs raw Serilog is kept minimal — no reflection at log time, level checks short-circuit before routing evaluation.

Full benchmark results (auto-updated on each release) →

Benchmarks run with BenchmarkDotNet on .NET 9, comparing LoggerHelper v5 against Serilog (baseline) and NLog using no-op sinks to measure framework overhead independently of I/O.

Target frameworks

TODO

Planned for upcoming releases — contributions welcome.

• Source Generator — replace runtime reflection for sink loading with a compile-time source generator: faster startup, AOT-compatible, trimming-safe
• BenchmarkDotNet suite — published performance comparisons vs Serilog pure, NLog, and Microsoft.Extensions.Logging default provider
• dotnet new template — dotnet new loggerhelper-api scaffolds a pre-configured project with zero friction
• Dashboard sink — embedded real-time UI showing active sinks, routing rules, and recent sink errors
• xUnit sink — forwards log output to xUnit test runner for integration test visibility
• AI extension — natural language log queries, anomaly detection, and incident summarization via LLM
• Telemetry extension — OpenTelemetry metrics export (log counters per sink, error rates, latency)
• Interactive playground — browser-based editor to test JSON routing config and see live output

License

MIT — © Alessandro Chiodo

Documentation · GitHub · NuGet