LowCodeHub.Logging 0.0.3

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, Application Insights, 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(
    loggingSection: "LoggingOptions",
    telemetrySection: "TelemetryOptions");

var app = builder.Build();

app.UseHttpContextEnricher();

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

That's it. Your application now has structured console + file logging, HTTP request enrichment (with PII-safe defaults), exception destructuring for Refit/EF Core/SqlClient, and optional Application Insights — all from two lines of setup.

Table of Contents

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

Configuration

Full Configuration Example

{
  "LoggingOptions": {
    "ServiceName": "orders-api",
    "MinimumLogLevel": "Information",
    "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"]
    },
    "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"
    }
  },
  "TelemetryOptions": {
    "Enabled": false,
    "ConnectionString": ""
  }
}

Logging Options

Console Logging

File Logging

Request Enrichment

Forwarded Headers

Self-Diagnostics

Application Insights

When Enabled=true, the library registers AI telemetry and writes Serilog traces to the DI-managed TelemetryConfiguration.

Exception Destructuring

Built-in destructurers extract structured data from common exception types:

These are registered automatically — no additional configuration needed.

HTTP Context Enrichment

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

The enricher adds contextual properties to every log entry during HTTP request processing. What gets logged depends on your RequestEnrichment configuration:

• Always: Request path, HTTP method, response status code, client IP
• Opt-in: Query string (allowlisted keys only), authenticated user, user roles, User-Agent, Referer

Health endpoint logs (/health path) are excluded by default.

How It Works

┌─────────────────────────────────────────────────────────┐
│  AddEnhancedSerilogLogging(loggingSection, telemetry)   │
└─────────────────────┬───────────────────────────────────┘
                      │
    ┌─────────────────┼─────────────────┐
    ▼                 ▼                 ▼
┌──────────┐   ┌──────────────┐   ┌──────────────────┐
│ Serilog  │   │ Enrichers    │   │ Destructurers    │
│ Sinks    │   │              │   │                  │
├──────────┤   ├──────────────┤   ├──────────────────┤
│Console   │   │Service Name  │   │ApiException      │
│(compact  │   │Correlation   │   │DbUpdateException │
│ JSON)    │   │HTTP Context  │   │SqlException      │
│          │   │Machine Name  │   │                  │
│File      │   │Environment   │   │                  │
│(rolling) │   │Thread        │   │                  │
│          │   │              │   │                  │
│App       │   │              │   │                  │
│Insights  │   │              │   │                  │
└──────────┘   └──────────────┘   └──────────────────┘

1. Configuration validation — Options 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. Enable Application Insights only when you provide a valid connection string.

Requirements

• .NET 10 or later
• Serilog.AspNetCore 10.0+ (included as a dependency)
• Microsoft.ApplicationInsights.AspNetCore (included — optional, enable via config)

License

MIT © Ahmed Abuelnour