SolTechnology.Core.Logging 1.2.0

SolTechnology.Core.Logging

Production-ready logging primitives for ASP.NET Core on top of Microsoft.Extensions.Logging. Pull it in and your app gets a W3C-compliant correlation id on every request, status-aware request envelope logs, declarative log-scope enrichment, allocation-free operation lifecycle events, and an OpenTelemetry-friendly ActivitySource — with zero ambient state and no Serilog or Application Insights dependency required.

Features

• W3C correlation id — traceparent + X-Correlation-Id resolved from the inbound request and echoed on the response. Same id flows through the log scope, downstream HTTP calls, and Activity.Current.
• Request envelope logs — one Started / Finished pair per request with log levels aligned to the status code (Information < 400, Warning 4xx, Error 5xx) and Warning for client aborts.
• Declarative scope enrichment — promote a header, route value, query parameter, or JSON body field into the per-request log scope with one DI line: services.LogDetail("X-Tenant-Id", asName: "TenantId", source: LogDetailSource.Header).
• Custom enrichers — drop in ILogScopeEnricher for anything the declarative form can't express (claims, async lookups, multi-source values).
• Request-header scope with PII masking — opt-in dump of every inbound header into the scope; sensitive values (Authorization, Cookie, anything starting with Bearer ) are masked before they reach any sink.
• Operation lifecycle events — OperationStarted / OperationSucceeded / OperationFailed with stable EventIds (2137–2140) and [LoggerMessage] source generators (allocation-free, short-circuits when disabled).
• Per-request timing diagnostics — ITimingService.StartContext("name") records named sub-context durations; the aggregated map is emitted in the "Finished request" log automatically. Lightweight "where did the time go?" without a full APM.
• OpenTelemetry tracing — CoreLoggingActivitySources.OperationsName ready to plug into WithTracing(...).AddSource(...). Zero cost when no listener attaches.
• Skip-paths for liveness / metrics noise — silences envelope logs for /health, /metrics, /swagger, etc., while still propagating correlation.

Registration

// Program.cs
builder.Services.AddSolLogging();                       // or .AddSolLogging(opts => { ... })
                                                         // or .AddSolLogging(builder.Configuration)

var app = builder.Build();
app.UseSolLogging();   // EARLY — before UseRouting / UseEndpoints
app.UseRouting();
app.UseAuthorization();
app.MapControllers();

AddSolLogging is idempotent; safe to call from multiple module installers. Place UseSolLogging before UseRouting so requests that fail authentication still get a correlation id and an envelope log entry.

Configuration

LoggingOptions bind from Logging:Core:

{
  "Logging:Core": {
    "MaxLoggedJsonBodyBytes": 65536,
    "LogRequestHeaders": false,
    "SkipPaths": [ "/health", "/alive", "/metrics", "/swagger" ],
    "MaskedHeaders": [ "Authorization", "Cookie", "X-Api-Key" ]
  }
}

builder.Services.AddSolLogging(builder.Configuration);
// or:
builder.Services.AddSolLogging(o => o.SkipPaths = LoggingDefaults.InfrastructurePaths.ToList());

Usage

Correlation id from anywhere

Inbound resolution order: current Activity.TraceId → inbound X-Correlation-Id (only when no Activity is in scope) → a freshly generated 32-character hex id. Both traceparent and X-Correlation-Id are echoed on the response.

public sealed class AuditWriter(ICorrelationIdService correlation, ILogger<AuditWriter> logger)
{
    public Task WriteAsync(string action, CancellationToken ct)
    {
        var id = correlation.GetOrGenerate();   // creates one for non-HTTP entry points
        logger.LogInformation("Audit [{Action}] correlation [{Correlation}]", action, id);
        return Task.CompletedTask;
    }
}

Declarative scope enrichment — LogDetail

// Header → scope["TenantId"]
builder.Services.LogDetail("X-Tenant-Id", asName: "TenantId", source: LogDetailSource.Header);

// Query / route key → scope["UserId"]
builder.Services.LogDetail("userId", source: LogDetailSource.Url);

// JSON body field "name" → scope["CityName"], only on these endpoints
builder.Services.LogDetail(
    "name",
    asName: "CityName",
    source: LogDetailSource.Body,
    endpoints: ["/api/v1/FindLocationOfCity", "/api/FindCityByName"]);

Body parsing is opt-in (only when a LogDetailSource.Body registration exists), bounded by MaxLoggedJsonBodyBytes, runs only on application/json, restores the request stream so MVC model binding still works, and silently no-ops on malformed JSON.

Custom enricher — ILogScopeEnricher

public sealed class UserScopeEnricher : ILogScopeEnricher
{
    public void Enrich(HttpContext context, IDictionary<string, object?> scope)
    {
        if (context.User?.Identity?.IsAuthenticated == true)
            scope["UserId"] = context.User.FindFirst("sub")?.Value;
    }
}

builder.Services.AddSolLogScopeEnricher<UserScopeEnricher>();

A faulty enricher cannot take a request down — the middleware catches and warns on enricher failures.

Request headers in the scope (opt-in, PII-safe)

builder.Services.AddSolLogging(o =>
{
    o.LogRequestHeaders = true;
    o.MaskedHeaders = LoggingDefaults.SensitiveHeaders
        .Concat(new[] { "X-Internal-Token" })
        .ToList();
});

Masking rules:

When LogRequestHeaders = false the enricher short-circuits in O(1) without iterating headers.

Operation lifecycle events

var sw = ValueStopwatch.StartNew();
logger.OperationStarted(nameof(ImportInvoices), message: "batch=123");
try
{
    await ImportAsync(ct);
    logger.OperationSucceeded(nameof(ImportInvoices), sw.ElapsedMilliseconds);
}
catch (Exception ex)
{
    logger.OperationFailed(nameof(ImportInvoices), sw.ElapsedMilliseconds, ex);
    throw;
}

Inside a CQRS pipeline these are emitted automatically via the [LogScope] attribute — see SolTechnology.Core.CQRS.

OpenTelemetry

builder.Services.AddOpenTelemetry()
    .WithTracing(t => t
        .AddSource(CoreLoggingActivitySources.OperationsName)   // MediatR operations
        .AddAspNetCoreInstrumentation()
        .AddHttpClientInstrumentation()
        .AddOtlpExporter());

Result in App Insights / structured sink

Testing

No dedicated fixture — use Microsoft.Extensions.Logging.Testing.FakeLogger (or NSubstitute on ILogger<T>) and assert on the captured entries. For component tests, APIFixture<TEntryPoint> from SolTechnology.Core.API.Testing already wires AddSolLogging + UseSolLogging, so correlation flows end-to-end out of the box.

[Test]
public async Task Endpoint_AcceptsCorrelationId_AndEchoesItBack()
{
    // Arrange
    var client = _fixture.CreateClient();
    var correlation = "0123456789abcdef0123456789abcdef";
    client.DefaultRequestHeaders.Add("X-Correlation-Id", correlation);

    // Act
    var response = await client.GetAsync("/api/trips/42");

    // Assert
    response.Headers.GetValues("X-Correlation-Id").Should().ContainSingle().Which.Should().Be(correlation);
}

Scope helpers

using SolTechnology.Core.Logging;

using var scope = logger.PushToScope("TenantId", tenantId);
// or multiple:
using var scope = logger.PushToScope(("TenantId", tenantId), ("Region", region));

PII masking

using SolTechnology.Core.Logging.Masking;

PiiMask.Full("secret@email.com");        // "***MASKED***"
PiiMask.Partial("secret@email.com", 3);  // "sec***com"

On CQRS requests, combine [LogScope] with [Masked]:

[LogScope, Masked(MaskMode.Partial, keepChars: 4)]
public string Email { get; set; } = null!;
// scope["Email"] = "john***.com"

Conventions

• UseSolLogging runs before UseRouting. Otherwise pre-routing failures (auth challenges, 404s) leave production without a correlation id.
• IncludeScopes: true in the console formatter — any sink that should see correlation / enrichment properties (Console JSON, App Insights, Loki, Datadog) requires it.
• {PascalCase} placeholders — matches MEL / Serilog / App Insights and the KQL queries consumers will write. See ClaudeCodingGuide.md §11.
• Wrap values in [] in every placeholder. Empty becomes [] instead of invisible.
• Never log secrets. Add the header to MaskedHeaders; never craft a bespoke log line that bypasses the enricher.
• Production levels: Default: Warning, Microsoft.Hosting.Lifetime: Information, SolTechnology.Core.Logging.Middleware.LoggingMiddleware: Information, SolTechnology.Core.CQRS.PipelineBehaviors.LoggingPipelineBehavior: Information.

What ships in DI

AddSolLogging registers:

• ICorrelationIdService — ambient correlation accessor (singleton, no AsyncLocal traps).
• ITimingService — per-request timing diagnostics (scoped). Handlers wrap sub-operations in StartContext("name") and the map is emitted on finish.
• TimeProvider — TimeProvider.System (singleton, TryAdd — your custom registration wins for testing).
• LoggingOptions — bound and validated on application start.
• LoggingMiddleware — request envelope + scope composition, activated by UseSolLogging.
• ILogScopeEnricher set — declarative LogDetail registrations plus any custom enricher you add via AddSolLogScopeEnricher<T>().
• CoreLoggingActivitySources — OperationsName activity source for OpenTelemetry plumbing.

All registrations are TryAdd* so a consumer's custom registration always wins.

Per-request timing diagnostics (ITimingService)

A lightweight "where did the time go in this request?" breakdown — without a full APM. Handlers wrap sub-operations in using (timingService.StartContext("name")) and the aggregated { name → elapsed ms } map is emitted automatically in the "Finished request" log:

Finished request [GET] [/api/v2/cities/find] -> [200] in [156 ms] — timings: [{"http": 120, "cache": 2}]

Registration

Registered automatically by AddSolLogging() — no extra call needed.

Usage (in a handler or service)

public class FindCityByNameHandler(
    ICityDomainService cityDomainService,
    ITimingService timingService) : IQueryHandler<FindCityByNameQuery, City>
{
    public async Task<Result<City>> Handle(FindCityByNameQuery query, CancellationToken ct)
    {
        City result;

        using (timingService.StartContext("http"))
        {
            result = await cityDomainService.Get(query.Name);
        }

        using (timingService.StartContext("cache"))
        {
            result = await cityDomainService.Get(query.Name);
        }

        return result;
    }
}

API

Design notes

• Scoped — each HTTP request gets its own TimingService instance (no cross-request leakage).
• TimeProvider-sourced — all timing reads go through TimeProvider (testable with FakeTimeProvider).
• Idempotent dispose — double-disposing a handle is safe (second dispose is a no-op).
• Zero cost when unused — if no handler calls StartContext, the "Finished request" log omits the timings field entirely (no empty {} noise).
• Aggregates, not traces — this is a request-level summary, not a span tree. For full distributed tracing, wire CoreLoggingActivitySources into OpenTelemetry.

Recipe: Singleton→scoped correlation bridge (background workers)

This is a pattern, not shipped code. The shape is too tenant-model-coupled to generalise into a library primitive. Copy and adapt.

A singleton background worker (Hangfire job, BackgroundService) has no HTTP request scope — so ICorrelationIdService is empty and DI scoped services aren't available. The recipe spins a DI scope manually and attaches correlation + principal context:

public class SettlementPollerJob(IServiceScopeFactory scopeFactory, ICorrelationIdService correlation)
{
    public async Task ExecuteAsync(CancellationToken ct)
    {
        // 1. Generate a correlation for this background unit-of-work
        var correlationId = CorrelationId.Generate();
        correlation.Set(correlationId);

        // 2. Spin a DI scope (so scoped services like DbContext are fresh)
        await using var scope = scopeFactory.CreateAsyncScope();
        var handler = scope.ServiceProvider.GetRequiredService<ISettlementHandler>();

        // 3. Push a log scope so every log in this UoW carries the correlation
        using var logScope = scope.ServiceProvider
            .GetRequiredService<ILogger<SettlementPollerJob>>()
            .BeginScope(new Dictionary<string, object?>
            {
                ["CorrelationId"] = correlationId.Value,
                ["JobName"] = "SettlementPoller"
            });

        // 4. Do the work
        await handler.ProcessAsync(ct);
    }
}

Key points:

• ICorrelationIdService is singleton — set it before starting work so downstream HTTP calls (CorrelationPropagatingHandler) pick it up.
• Dispose the scope when done — DbContext, IIdempotencyStore, etc. are released.
• For Hangfire jobs: Core.Hangfire's CorrelationIdJobFilter does steps 1+3 automatically. Use this pattern only for raw BackgroundService or custom polling loops.