DcsvIo.D2.Logging 0.1.2

DcsvIo.D2.Logging

Serilog configuration + the [RedactData] enforcement layer + an ASP.NET Core request-logging middleware. Foundation lib that other shared libs and per-service composition roots call to wire the Serilog pipeline + the [RedactData] destructuring policy + the request-logging middleware (services call AddD2Logging instead of duplicating ~30 lines of LoggerConfiguration boilerplate per service). Also usable standalone by any host that wants the same Serilog setup without an aggregator.

Install

dotnet add package DcsvIo.D2.Logging

The lib does NOT own:

• OpenTelemetry SDK setup — out of scope. Logs reach OTLP collectors via the MEL pipeline (writeToProviders: true routes Serilog output to other registered ILoggerProviders); the OTLP log-exporter wiring is owned by separate observability infrastructure.
• [LoggerMessage] source-generated delegates — this lib bootstraps the log pipeline itself; logging inside its own bootstrap path would be circular.
• Activity / span enrichment (e.g. Serilog.Enrichers.Span) — out of scope; observability infrastructure owns activity / span emission separately.

Public API surface

Composition

services.AddD2Logging(configuration, opts =>
{
    opts.ServiceName = "edge";       // optional — defaults from OTEL_SERVICE_NAME → IHostEnvironment.ApplicationName
    opts.Environment = "Production"; // optional — defaults from IHostEnvironment.EnvironmentName
    opts.MinimumLevel = LogEventLevel.Information; // optional — default Information
});

// later, inside the middleware pipeline:
app.UseRouting();
app.UseD2RequestLogging(); // optional configure callback
app.UseEndpoints(...);

AddD2Logging(IConfiguration, Action<D2LoggingOptions>?) builds the Serilog LoggerConfiguration, sets Log.Logger, and wires the MEL bridge (AddSerilog(preserveStaticLogger: true, writeToProviders: true)). Validates options at the first IOptions<D2LoggingOptions>.Value resolution (typically host-startup composition) via ValidateOnStart() — fail-fast on invalid config.

UseD2RequestLogging(Action<RequestLoggingOptions>?) wraps Serilog's UseSerilogRequestLogging with the D² defaults: per-source minimum-level overrides, infrastructure-path suppression (logged at Verbose so the default minimum-level gate filters them out), conservative diagnostic-context enrichment, and projection of the spec-driven IRequestContext LOG-OK fields onto the request-completion event.

Configuration — D2LoggingOptions

Constants

D2LoggingConstants.OTEL_SERVICE_NAME_CONFIG_KEY — the "OTEL_SERVICE_NAME" configuration key consulted for the ServiceName default. Matches the OpenTelemetry-canonical convention so log + trace + metric service names stay aligned across the log + trace + metric pipelines without this lib taking an OpenTelemetry SDK dependency itself.

Per-source overrides

AddD2Logging applies these per-source minimum-level overrides on top of the configured MinimumLevel:

Suppresses the framework / HTTP-client noise that Information-level produces by default while keeping D² code's diagnostic logs visible.

Enrichers

Output sink

Console with CompactJsonFormatter (terse JSON to stdout). When other ILoggerProviders are registered against builder.Logging (e.g. an OTLP log-exporter from observability infrastructure), Serilog routes events through both sinks via writeToProviders: true.

Network/IP enrichment design

The middleware does NOT log the request's connection-remote IP address (HttpContext.Connection.RemoteIpAddress). Two reasons:

• At internal services, that address is the upstream Edge instance's IP, not the original client's. Operators reading logs would interpret it as the user's IP, which it isn't — a data-shape footgun.
• At Edge, the resolved client IP is PII. Logging it as a structured-context field would bypass the [RedactData] destructuring policy entirely (diagnostic-context Set writes a ScalarValue directly).

Geo / network-privacy / ASN / identity / impersonation / tracing fields are projected from the spec-driven IRequestContext onto the request-completion log line via D2RequestContextEnricher. The enricher is always-on; it gracefully no-ops when IRequestContext isn't in DI scope. Each per-field Set is gated by a null check; null fields are not emitted at all (vs an emitted-null structured property). Collection fields (Audience, ActorChain, Scopes) gate on Truthy() so empty collections don't pollute logs with empty arrays on every request.

Why log identity at the request-context axis

Internal logs are read by operators who already have tenant access to query org / user metadata via authenticated APIs; emitting identity into the request-completion log line is operationally invaluable for "show me Alice's requests across this trace" debugging without any incremental disclosure beyond what those same operators can already query directly. The trade-off is intentional: every log line that fires inside the user's own access boundary already carries identity through trace + correlation IDs anyway; the enricher just makes the linkage one hop shorter.

Precedence note — TraceId, RequestId, RequestPath

The three Tracing-axis fields collide with values that the request-logging middleware emits independently. The override behavior differs per field because of how each upstream value reaches the log event.

• TraceId — enricher WINS when populated. The middleware sets TraceId via IDiagnosticContext.Set("TraceId", httpContext.TraceIdentifier) early in the EnrichDiagnosticContext callback. The enricher runs LAST in that callback and writes via the same IDiagnosticContext mechanism — last-writer-wins on the same diagnostic-context dictionary. When IRequestContext.TraceId is populated (carrying the W3C distributed-trace id), the enricher overrides the local HttpContext.TraceIdentifier value. When unpopulated, the middleware's value survives. Operators reading logs should treat TraceId as the W3C value when IRequestContext is wired and as HttpContext.TraceIdentifier otherwise.
• RequestId — Serilog WINS on the HTTP path. Serilog 9.x's RequestLoggingMiddleware emits RequestId via its own ForContext binding before the EnrichDiagnosticContext callback runs. Once Serilog has set the property on the LogEvent, subsequent IDiagnosticContext.Set("RequestId", ...) calls are silently dropped by Serilog's AddPropertyIfAbsent semantics. The enricher's emission of IRequestContext.RequestId is included for spec-contract completeness — on transports where Serilog does NOT pre-bind RequestId (custom diag-ctx integrations on non-HTTP transports), the enricher's value will appear.
• RequestPath — Serilog WINS on the HTTP path. Same rationale as RequestId. Serilog's request-completion message template binds RequestPath from HttpContext.Request.Path via ForContext before the enricher runs; the enricher's emission is silently dropped on HTTP. On AMQP / messaging transports without the same template binding, the enricher's value would appear.

The two HTTP-path limitations (RequestId and RequestPath) reflect Serilog's request-logging middleware design, not a bug in the enricher. Carrying the same emission contract across all transports (HTTP + AMQP + future) is the spec-driven discipline; the limitation is documented here so operators know RequestPath in HTTP logs is always the local path and RequestId is always the local TraceIdentifier.

LOG-OK fields (emitted when populated)

42 fields organized into 11 clusters. Every field is null-gated (collections gated on Truthy()); unpopulated fields don't reach the log line.

Tracing (3 fields)

Auth/Identity (8 fields)

Auth/Token+Trust (5 fields)

Auth/Org (4 fields)

Auth/Impersonation (8 fields)

Scopes (1 field)

Trust/Risk (1 field)

Fingerprints (2 fields)

WhoIs/Geo (3 fields)

WhoIs/Network-Privacy (4 fields)

WhoIs/ASN (3 fields)

NOT-LOGGED fields (suppressed at default)

8 fields. The first 5 are explicitly user-pinned PII; the last 3 (lat/long/geohash) are §3-driven (geographic precision = identification primitive — geohash IS lat/long, just hex-encoded). Sub-country geographic precision escalates only via WhoIsHashId lookups against the WhoIs store (operators with auth can dereference when a real investigation needs it).

Opting in to additional fields

Callers can chain into the existing RequestLoggingOptions.EnrichDiagnosticContext callback:

app.UseD2RequestLogging(opts =>
{
    var existing = opts.EnrichDiagnosticContext;
    opts.EnrichDiagnosticContext = (diag, http) =>
    {
        existing?.Invoke(diag, http);
        diag.Set("MyCustomField", ResolveCustomField(http));
    };
});

⚠️ Caller-added structured fields BYPASS the [RedactData] destructuring policy (the diagnostic-context path emits ScalarValues directly). Callers MUST own PII discipline for anything they add. If the data is PII, log a [RedactData]-decorated wrapper object using the destructuring capture mode ({@MyObj}) inside a LoggerScope instead.

Destructuring discipline

RedactDataDestructuringPolicy enforces the [RedactData] attribute defined in DcsvIo.D2.Utilities.Attributes. It runs on every @-captured object in every ILogger.Log* call across every service that wires AddD2Logging. Three rules to know:

1. Capture mode matters. Serilog's @-prefix invokes destructuring; the policy fires. The default {prop} capture (without @) calls .ToString() on the value and bypasses destructuring entirely. If you have [RedactData] on a record and write logger.Information("user {User}", user), the record's default ToString() includes property values verbatim — leaks the PII the attribute was supposed to redact.
2. Field-level [RedactData] is silently ignored. The policy reflects over BindingFlags.Public | Instance PROPERTIES only — no fields. Use property syntax for redaction.
3. Computed properties leak through their inputs. A public string DisplayName => $"{First} {Last}" is destructured even if First carries [RedactData]. Redact the computed property too if its inputs are PII.

Redaction modes

Reason rendering uses the enum name (PersonalInformation, FinancialInformation, SecretInformation, VerboseContent, Other, Unspecified) unless a CustomReason overrides it.

Types (source map)

Dependencies

Edge cases / gotchas

• Log.Logger is a process-global static. AddD2Logging SETS it. Tests that build multiple hosts in one process see the LATEST host's logger on the static. The lib's integration tests pin this behavior with [Collection("LogLoggerStaticState")] to serialize against any other test that touches the static.
• Microsoft.NET.Sdk.Web defaults OutputType to Exe. This csproj overrides to Library explicitly — same shape as other ASP.NET-library siblings.
• No Microsoft.Extensions.{DependencyInjection,Logging,Options}.Abstractions PackageReferences. The framework reference (Microsoft.AspNetCore.App) ships them; explicit references would trigger NU1510 ("will not be pruned"). Versions remain pinned via Directory.Packages.props.
• InfrastructurePathMatcher lives in DcsvIo.D2.AspNetCore — single source of truth. UseD2RequestLogging's level callback consumes the public matcher; DcsvIo.D2.Telemetry's AspNetCore-instrumentation Filter consumes the same one. The path set (/health, /alive, /metrics, /.well-known) stays aligned across the two consumers without per-lib duplication.
• The integration-test contract pins the absent PII fields. RequestContextEnricherIntegrationTests enumerates every IRequestContext NOT-LOGGED field (the 8 enumerated above: ClientIp, City, Region, SubdivisionCode, PostalCode, Latitude, Longitude, Geohash) and asserts NONE appear in the rendered JSON output. Adding a new PII field to the spec without a coverage update is a contract failure that surfaces at test time.