LowCodeHub.Logging 0.0.11

LowCodeHub.Logging

A production-oriented logging library for ASP.NET Core built on Serilog. One extension method configures structured logging, HTTP request enrichment, sensitive data masking, file/console sinks, forwarded headers, and self-diagnostics — with safe defaults and PII-conscious enrichment.

Why This Library?

Installation

dotnet add package LowCodeHub.Logging

Quick Start

using LowCodeHub.Logging.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.AddEnhancedSerilogLogging(); // binds the "LoggingOptions" section

var app = builder.Build();

app.UseHttpContextEnricher(); // uses the RequestEnrichment options bound above

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

That's it. Your application now has structured console + file logging, HTTP request enrichment (with PII-safe defaults), and sensitive data masking — all from two lines of setup.

Table of Contents

• Configuration
  • Full Configuration Example
  • Logging Options
  • Console Logging
  • File Logging
  • Request Enrichment
  • Sensitive Data Masking
  • Forwarded Headers
  • Self-Diagnostics
• Exception Destructuring
• HTTP Context Enrichment
• How It Works
• Best Practices
• Requirements
• License

Configuration

Full Configuration Example

{
  "LoggingOptions": {
    "ServiceName": "orders-api",
    "MinimumLogLevel": "Information",
    "LevelOverrides": {
      "Microsoft": "Warning",
      "System": "Warning"
    },
    "ExcludedRequestPaths": ["/health"],
    "WriteToFile": true,
    "ConsoleLogging": {
      "UseCompactJson": true,
      "Theme": "literate"
    },
    "FileLogging": {
      "LogDirectory": "Logs",
      "LogFileName": "app.log",
      "RollingInterval": "Day",
      "RetainedFileCountLimit": 14,
      "SharedFile": true
    },
    "ExceptionHandling": {
      "MaxDestructuringDepth": 3
    },
    "RequestEnrichment": {
      "IncludeQueryString": false,
      "IncludeAuthenticatedUser": false,
      "IncludeUserRoles": false,
      "IncludeUserAgent": true,
      "IncludeReferer": false,
      "AllowedQueryKeys": ["page", "pageSize"]
    },
    "SensitiveDataMasking": {
      "Enabled": true,
      "MaskValue": "***MASKED***",
      "MaskEmailAddresses": true,
      "MaskIbanNumbers": true,
      "MaskCreditCardNumbers": false,
      "MaskProperties": ["Password", "Token"],
      "ExcludeProperties": []
    },
    "ForwardedHeaders": {
      "Enabled": true,
      "ForwardLimit": 1,
      "RequireHeaderSymmetry": true,
      "KnownProxies": ["10.0.0.10"],
      "KnownNetworks": ["10.244.0.0/16"]
    },
    "SelfLog": {
      "Enabled": true,
      "WriteToConsoleError": true,
      "FilePath": "Logs/serilog-selflog.txt"
    }
  }
}

Logging Options

Console Logging

File Logging

Log files are written under the application content root (not the process working directory).

Request Enrichment

Sensitive Data Masking

Masking runs globally over rendered log messages and properties via Serilog.Enrichers.Sensitive.

Forwarded Headers

Invalid KnownProxies / KnownNetworks entries fail at startup, not at first request.

Self-Diagnostics

Serilog's SelfLog is process-global: the first host to configure it wins, and later configurations in the same process are no-ops.

Exception Destructuring

Serilog.Exceptions' default destructurers are always registered. For richer destructuring of third-party exception types, pass destructurers from the official satellite packages — they are no longer bundled, so this library does not force EF Core, SqlClient, or Refit onto your dependency graph:

dotnet add package Serilog.Exceptions.Refit               # Refit ApiException
dotnet add package Serilog.Exceptions.EntityFrameworkCore # EF Core DbUpdateException
dotnet add package Serilog.Exceptions.SqlServer           # Microsoft.Data.SqlClient SqlException

builder.AddEnhancedSerilogLogging(
    "LoggingOptions",
    new ApiExceptionDestructurer(),
    new DbUpdateExceptionDestructurer(),
    new SqlExceptionDestructurer());

HTTP Context Enrichment

app.UseHttpContextEnricher(); // register early in the middleware pipeline

The enricher adds contextual properties to every request-completion log entry. It automatically uses the RequestEnrichment options bound by AddEnhancedSerilogLogging; pass an options instance explicitly to override.

• Always: Request method, path, status code, protocol, host, scheme, trace identifier, client IP
• Opt-in: Query string (allowlisted keys only), authenticated user, user roles, User-Agent, Referer

Events for paths in ExcludedRequestPaths (default /health) are excluded.

How It Works

┌─────────────────────────────────────────────────────────┐
│  AddEnhancedSerilogLogging(loggingSection, ...)          │
└─────────────────────┬───────────────────────────────────┘
                      │
    ┌─────────────────┼─────────────────┐
    ▼                 ▼                 ▼
┌──────────┐   ┌──────────────┐   ┌──────────────────┐
│ Serilog  │   │ Enrichers    │   │ Destructurers    │
│ Sinks    │   │              │   │                  │
├──────────┤   ├──────────────┤   ├──────────────────┤
│Console   │   │Service Name  │   │Serilog.Exceptions│
│(compact  │   │Correlation Id│   │defaults          │
│ JSON)    │   │HTTP Context  │   │                  │
│          │   │Machine Name  │   │+ any you pass in │
│File      │   │Process Id/   │   │(Refit, EF Core,  │
│(rolling) │   │ Name         │   │ SqlClient, ...)  │
│          │   │Sensitive Data│   │                  │
│Debug     │   │ Masking      │   │                  │
└──────────┘   └──────────────┘   └──────────────────┘

1. Configuration validation — Options (including proxy IPs/CIDRs) are validated at startup. Invalid configuration fails fast.
2. Serilog bootstrap — Console + Debug sinks are configured first for startup logging.
3. Host integration — UseSerilog() replaces the default logger with the configured Serilog pipeline.
4. Request logging — Serilog's UseSerilogRequestLogging() adds HTTP request logging middleware.
5. HTTP enrichment — UseHttpContextEnricher() adds contextual properties per request.

Best Practices

1. Set a real ServiceName per service.
2. Keep IncludeQueryString=false unless you truly need it.
3. If query logging is enabled, use AllowedQueryKeys allowlist only.
4. Keep user identity fields disabled by default in public-facing APIs.
5. Configure KnownProxies / KnownNetworks in Kubernetes or behind ingress.
6. Enable SelfLog in production to catch sink/serialization failures.
7. Use compact JSON logs in containerized environments.
8. Keep file retention bounded to avoid disk exhaustion.
9. Add MaskProperties entries for any domain-specific secrets (tokens, national IDs).

Requirements

• .NET 10 or later
• Serilog.AspNetCore 10.0+ (included as a dependency)

License

MIT © Ahmed Abuelnour