Fuchs_Intranet/Fuchs/Docs/Concepts/error-logging-pipeline.md

status, lastUpdated, applyTo, relatedDecisions

status	lastUpdated	applyTo	relatedDecisions
Active	2026-09-16	Fuchs/Program.cs Fuchs/Logging/** Fuchs/code/FuchsIntranet.cs Fuchs/Controllers/** Fuchs/Observability/FuchsTelemetry.cs	0003-structured-diagnostic-logging.md 0003-interrupting-exceptions-notify-the-user.md 0004-opentelemetry-observability.md 0023-user-action-failures-persisted-to-db-log.md 0024-multilogger-sql-log-sink.md

Error logging pipeline

Summary

A _logger.LogWarning/-Error/-Critical call anywhere in the app — or in OCORE code called from it — reaches three places automatically: the always-on file sink, a DB row in [dbo].[fds__debuglog] (what support actually queries), and, for a user-initiated action that threw unhandled, a SignalR toast to the user. One ILogger call is the single thing a call site writes; nothing calls a stored procedure directly for attribution logging.

How it works

The two ILoggerProviders

• FuchsLoggerProvider (Fuchs/Logging/FuchsLoggerProvider.cs, 0003): every level ≥ Debug → Debug.WriteLine + a rolling-free text file (logs/AppLog.txt / logs/ErrorLog.txt). Always on, no DB dependency.
• OCORE.MultiLogger.SqlLoggerProvider (0024): registered in Program.cs via builder.Logging.AddSqlLogger(), gated by Fuchs:Logging:SqlSink:Enabled (default on), filtered to LogLevel.Warning+. Writes via EXECUTE [dbo].[fds__admin_logdebug_ext] into [dbo].[fds__debuglog] — the same table the legacy, now-unused fds__admin_logdebug proc wrote to.

Attribution: EventId, category, scope

• CodeReference (the row's short label) is COALESCE(EventId.Name, ILogger category, 'MultiLogger'), computed in the stored procedure. Give a log call an explicit EventId when the call site should be individually greppable:

  _logger.LogError(new EventId(0, "SQL Error in getSQLDataSet"), ex, "SQL error in {Procedure}: ...", ...);
  

  See FIS_SQLOptions.OnError, IntranetController.Do's catch-all, PdfPreviewAsync, and the bam/up (banking upload) handlers for the pattern — each preserves the exact string the old, explicit debug_log() calls used, so existing saved queries over CodeReference still match.
• RequestLogScopeMiddleware (Fuchs/Logging/RequestLogScopeMiddleware.cs, registered after app.UseAuthentication()) pushes {requestId, path, authuser} as an ILogger scope for the whole request. Every log line written while handling it — including ones written deep inside OCORE's SQL helpers — carries that automatically, without the call site doing anything. authuser specifically lands in the dedicated fds__debuglog.AuthUser column (OCORE's MultiLogger_base.Log picks the "authuser" scope key out into LogEntry.AuthUser); the rest of the scope + any {Placeholder} args + an explicit data: object are merged into one redacted JSON blob (fds__debuglog.Data).
• No request/service-scoped logger available (new FIS_SQLOptions() — ~15 call sites in Services/*.cs construct it this way): FIS_SQLOptions.OnError falls back to the static OCORE.Logging.Logger (set once in Program.cs to app.Logger), so those SQL errors are still attributed, just under a less specific category.

Placeholder naming

Always {Foo}, never {@Foo}. Plain Microsoft.Extensions.Logging (not Serilog) does not treat @ as a destructuring operator — it stays a literal leading character of the resulting property name ("@Foo"), which is confusing in the serialized Data column.

Redaction and cost

OCORE.MultiLogger.LogRedaction.SerializeRedacted masks property names matching known-sensitive fragments/segments (password, secret, token, pin, otp as a whole identifier segment — not substrings like Mapping/HotPath) at any nesting depth, degrades one unserializable context entry to its ToString() instead of losing the whole payload, and tolerates self-referencing graphs. LogEntry.dataSerialized is computed lazily — at most once, only if a sink actually reads it — so a Warning+ call that no sink is currently listening for costs nothing extra to serialize.

User-visible failure surface (unrelated to the DB write, 0023)

• IntranetController.Do's catch-all publishes a SignalR toast (IEventService.UserIssueAsync) for any unmodeled exception, for authenticated users only.
• A 500 response carries its message in the x-ocms-desc header (ServerError(msg) → EncodeResponseDescription), which the frontend's default failure handler ($ocms.failure/oci_basic.js) reads.
• PDF-preview endpoints go through the shared PdfPreviewAsync guard: logs, counts fuchs.pdf.previews{what,outcome} (success/gone/failure — an expired-draft 410 is its own gone outcome, not a render failure), toasts an authenticated caller, and returns a message with the innermost exception text (omitted for the handful of preview endpoints reachable without authentication — see _allowedGet in IntranetController.cs).

Configuration

• Fuchs:Logging:SqlSink:Enabled (bool, default true) — off switch for the SQL sink without a redeploy.
• SQL sink connects via fuchs_fds_ConnectionString (same connection as everything else), proc dbo.fds__admin_logdebug_ext, TruncateTextAt = 4000.

Extending this

• Adding a new sink (email/SMS on Critical, a rolling file replacing FuchsLoggerProvider) is a registration in Program.cs — OCORE.MultiLogger already ships EmailLoggerOptions/ SMSLoggerOptions/FileLoggerProvider.
• A new place that needs DB attribution just calls _logger.LogWarning/-Error with an EventId if it wants a specific CodeReference — never add a second, explicit stored-procedure call next to it; that duplicates the row once the SQL sink picks the ILogger call up.