ITSS.SimpleLogs 1.2.0

ITSS.SimpleLogs

A lightweight, consistent logging helper for ASP.NET Core (.NET 8) applications with first-class NLog and Serilog support, ready-to-use JSON layouts/formatter, HTTP enrichment middleware, and optional request body logging.

Highlights

• NLog and Serilog: code‑first setup or configuration file based.
• JSON logs: consistent schema with @t (timestamp), @l (level), @mt (message), @x (exception), traceId, logger, and enriched context properties.
• HTTP middleware: request start/finish logging, correlation via header (e.g., X-Correlation-Id), duration and status.
• Request body: conditional logging for POST/PUT/PATCH and only for 409/5xx responses, or always at Debug level.
• Configurable options: ability to configure request blacklist (case-insensitive prefix matching with path normalization) and custom correlation header name.

Requirements

• .NET 8 (net8.0)

Installation

dotnet add package ITSS.SimpleLogs

Current version: 0.5.0

Quick start (NLog)

1) Basic configuration in Program.cs:

var builder = WebApplication.CreateBuilder(args);

// Enable NLog with default options
builder.Host.UseSimpleNLog();

// Code-based NLog config (targets, rules, JSON layout, rolling, etc.)
var nlog = ITSS.SimpleLogs.SimpleLogsManager.InitNLogWithDefaultConfig();

var app = builder.Build();

// HTTP enrichment middleware
app.UseNLogHttpLoggingEnrichmentMiddleware();

// (Optional) request body logging for NLog – enabled only when the RequestBody logger is active
app.UseNLogRequestPostedBodyMiddleware();

app.MapGet("/ping", () => "pong");
app.Run();

2) Configuration with options:

var builder = WebApplication.CreateBuilder(args);

// Configuration with custom options
builder.Host.UseSimpleNLog(options =>
{
    options.CorrelationIdHeaderName = "X-Request-Id"; // Custom header name
    options.RequestsBlackList = ["/health", "/metrics"]; // Paths excluded from logging (case-insensitive prefix matching with path normalization)
});

var nlog = ITSS.SimpleLogs.SimpleLogsManager.InitNLogWithDefaultConfig();

var app = builder.Build();

app.UseNLogHttpLoggingEnrichmentMiddleware();
app.UseNLogRequestPostedBodyMiddleware();

app.MapGet("/ping", () => "pong");
app.Run();

3) Loading configuration from file:

// From appsettings.json
var nlog = SimpleLogsManager.InitNLogWithAppsettingsConfig();

// Or from XML file (e.g., nlog.config)
var nlog = SimpleLogsManager.InitNLogWithXmlConfig("nlog.config");

4) Minimal NLog section in appsettings.json:

{
  "NLog": {
    "autoReload": true,
    "throwConfigExceptions": true,
    "extensions": [ { "assembly": "ITSS.SimpleLogs" } ],
    "targets": {
      "allFile": {
        "type": "File",
        "fileName": "${basedir}/../Logs/WebApi.log",
        "archiveEvery": "Day",
        "archiveNumbering": "Rolling",
        "layout": { "type": "BaseCustomJsonLayout" }
      }
    },
    "rules": [
      { "logger": "*", "minLevel": "Info", "writeTo": "allFile" }
    ]
  }
}

Note: The default code configuration writes a single JSON log file (../Logs/WebApi.log relative to basedir) with daily rolling; special HTTP categories (Request/Response/Correlation/RequestBody) are routed to the same file.

Quick start (Serilog)

1) Basic configuration:

var builder = WebApplication.CreateBuilder(args);

// Enable Serilog with default options
builder.Host.UseSimpleSerilog();

// Default setup (console + file with BaseCustomJsonFormatter)
var serilog = SimpleLogsManager.InitSerilogDefaultConfig();

// Or from appsettings.json
// var serilog = SimpleLogsManager.InitSerilogWithAppsettingsConfig(builder.Configuration);

var app = builder.Build();

// HTTP enrichment middleware
app.UseSerilogHttpLoggingEnrichmentMiddleware();

app.MapGet("/ping", () => "pong");
app.Run();

2) Configuration with options:

var builder = WebApplication.CreateBuilder(args);

// Configuration with custom options
builder.Host.UseSimpleSerilog(options =>
{
    options.CorrelationIdHeaderName = "X-Request-Id";
    options.RequestsBlackList = ["/health", "/metrics"]; // Paths excluded from logging (case-insensitive prefix matching with path normalization)
});

var serilog = SimpleLogsManager.InitSerilogDefaultConfig();

var app = builder.Build();

app.UseSerilogHttpLoggingEnrichmentMiddleware();

app.MapGet("/ping", () => "pong");
app.Run();

3) Example Serilog section in appsettings.json:

{
  "Serilog": {
    "Using": [ "Serilog.Sinks.Console", "Serilog.Sinks.File" ],
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "ITSS.SimpleLogs.Middlewares.SerilogHttpLoggingEnrichmentMiddleware.RequestBody": "Information"
      }
    },
    "WriteTo": [
      { "Name": "Console" },
      {
        "Name": "File",
        "Args": { "path": "Logs/log-.txt", "rollingInterval": "Day" }
      }
    ],
    "Enrich": [ "FromLogContext" ]
  }
}

Request body logging controls

When is it logged:

• By default: for POST/PUT/PATCH and only for 409/5xx responses
• Always: when the RequestBody category runs at Debug level

NLog:

• Category: ITSS.SimpleLogs.Middlewares.NLogHttpLoggingEnrichmentMiddleware.RequestBody
• Enable: via NLog rules (e.g., minLevel=Info) and use HttpRequestBodyCustomJsonLayout to emit the Body field
• Middleware: UseNLogRequestPostedBodyMiddleware() wires NLog.Web.NLogRequestPostedBodyMiddleware conditionally only when the logger is active

Serilog:

• Category: ITSS.SimpleLogs.Middlewares.SerilogHttpLoggingEnrichmentMiddleware.RequestBody
• Enable: via MinimumLevel.Override
• Operation: the middleware buffers and reads the body (EnableBuffering)

API Quick Reference

SimpleLogsManager (NLog)

• InitNLogWithDefaultConfig(Action<LoggingConfiguration>? configure = null) – code-based NLog setup (targets, rules, JSON layouts). You can mutate the config via the callback.
• InitNLogWithAppsettingsConfig() – registers custom layouts and loads NLog from appsettings.json.
• InitNLogWithXmlConfig(string xmlFilePath) – loads NLog from XML and registers layouts.
• ConfigureBaseLayout(Action<BaseCustomJsonLayout> configure) – runtime JSON layout tweaks for base layout.
• ConfigureRequestLayout(Action<HttpRequestCustomJsonLayout> configure) – runtime JSON layout tweaks for HTTP requests.
• ConfigureResponseLayout(Action<HttpResponseCustomJsonLayout> configure) – runtime JSON layout tweaks for HTTP responses.
• ConfigureRequestBodyLayout(Action<HttpRequestBodyCustomJsonLayout> configure) – runtime JSON layout tweaks for request body.
• ShutdownNLog() – flushes and shuts down NLog, releasing file handles and other resources.

SimpleLogsManager (Serilog)

• InitSerilogDefaultConfig() – default Serilog setup (console + file using BaseCustomJsonFormatter).
• InitSerilogWithAppsettingsConfig(IConfiguration) – Serilog setup from appsettings.json.

IHostBuilderExtensions

• UseSimpleNLog(Action<SimpleLogsOptions>? options = null, Action<NLogAspNetCoreOptions>? configure = null) – configures NLog for the host with optional parameters.
• UseSimpleSerilog(Action<SimpleLogsOptions>? options = null, Action<HostBuilderContext, IServiceProvider, LoggerConfiguration>? configure = null) – configures Serilog for the host with optional parameters.

IApplicationBuilderExtensions

• UseNLogHttpLoggingEnrichmentMiddleware() – HTTP middleware for NLog.
• UseSerilogHttpLoggingEnrichmentMiddleware() – HTTP middleware for Serilog.
• UseNLogRequestPostedBodyMiddleware() – conditional request body reader for NLog.

LoggingExtensions

• LogException(this ILogger, Exception) – helper to log exceptions as Error.

SimpleLogsOptions

public class SimpleLogsOptions
{
    public string[] RequestsBlackList { get; set; } = [];
    public string CorrelationIdHeaderName { get; set; } = "X-Correlation-Id";
}

JSON Log Format

Common fields (example):

{
  "@t": "2025-01-01T12:34:56.1234567Z",
  "@l": 2,
  "@mt": "Request completed.",
  "@x": null,
  "traceId": "00-<traceId>-<spanId>-00",
  "logger": "ITSS.SimpleLogs.Middlewares.SerilogHttpLoggingEnrichmentMiddleware+Response",
  "StatusCode": 200,
  "Duration": 123
}

Additional fields:

• For requests: Form, QueryString, Path, Method, Env, Hostname
• For request body: Body
• For responses: StatusCode, Duration

Best Practices and Middleware Order

Recommended pipeline order:

1. Global exception handling
2. HTTP logging middleware (UseNLogHttpLoggingEnrichmentMiddleware() or UseSerilogHttpLoggingEnrichmentMiddleware())
3. Request body middleware (UseNLogRequestPostedBodyMiddleware() - optional)
4. Routing and endpoints

Correlation configuration:

• By default, the X-Correlation-Id header is used
• Can be changed via SimpleLogsOptions.CorrelationIdHeaderName

Request blacklist:

• Use SimpleLogsOptions.RequestsBlackList to exclude paths from logging. The middleware normalizes the request path by appending "/" and then checks if it starts with any path from the blacklist (case-insensitive comparison).
• Important: There is a difference between /health and /health/ in the blacklist:
  • /health in blacklist will match /health, /health/, /health/check, /healthcheck, and any path starting with /health (case-insensitive)
  • /health/ in blacklist will match only /health/ and /health/check, but NOT /health or /healthcheck
• Example: blacklist ["/health", "/metrics"] will exclude /health, /health/check, /healthcheck, /metrics, /metrics/prometheus, and any path starting with /health or /metrics (case-insensitive).

Available Layouts (NLog)

• BaseCustomJsonLayout – base JSON layout for general logs
• HttpRequestCustomJsonLayout – layout for HTTP request logs
• HttpResponseCustomJsonLayout – layout for HTTP response logs
• HttpRequestBodyCustomJsonLayout – layout for HTTP request body logs

Dependencies

NLog packages:

• NLog (6.0.3)
• NLog.Web.AspNetCore (6.0.3)
• NLog.DiagnosticSource (6.0.2)
• NLog.Targets.AtomicFile (6.0.3)

Serilog packages:

• Serilog (4.3.0)
• Serilog.AspNetCore (9.0.0)
• Serilog.Sinks.Console (6.0.0)
• Serilog.Sinks.File (7.0.0)

License

See LICENSE.txt. Usage is restricted to applications delivered by ITSS according to the relevant agreements.

Changelog

See CHANGELOG.md for the complete project change history.