dohertj2/scadaproj
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(telemetry.serilog): don't set process-global Log.Logger in AddZbSerilog (multi-host safe)

Browse Source 
Remove the Stage-1 bootstrap-logger line (Log.Logger = new LoggerConfiguration()
.WriteTo.Console().CreateBootstrapLogger()) from AddZbSerilog. A shared library must
not mutate process-global state: when multiple hosts are built in one process (integration
tests, Aspire multi-host, parallel test runs) the second call throws "The logger is
already frozen".

AddSerilog is now called with preserveStaticLogger: true so Serilog.Extensions.Hosting
leaves the static Log.Logger entirely untouched. The DI-registered application logger is
the only artifact AddZbSerilog produces.

Apps that want a pre-Build() bootstrap logger should set Log.Logger themselves in
Program.cs before calling AddZbSerilog — that decision belongs to the application.

Three new regression tests in MultiHostTests verify: two hosts build in the same process
without throwing; Log.Logger is not mutated; each host gets its own independent DI ILogger.

Docs (SPEC.md §5 and shared-contract ZB.MOM.WW.Telemetry.md) updated: the "two-stage
bootstrap" framing is replaced with the correct description — library registers only the
DI application logger; optional Stage-1 bootstrap is the app's responsibility.
This commit is contained in:
Joseph Doherty
2026-06-01 08:13:35 -04:00
parent f1240c0bd4
commit f569d537d1
4 changed files with 186 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files
components/observability/spec/SPEC.md
+18 -7
View File
@@ -108,13 +108,24 @@ three apps currently use or aspire to.
## 5. Serilog logging stack
`AddZbSerilog` is a companion extension in the `.Serilog` package. It replaces each
project's bespoke logging bootstrap with a shared two-stage pattern:
`AddZbSerilog` is a companion extension in the `.Serilog` package. It registers the
Serilog application logger in DI and applies a set of fixed enrichers:
**Stage 1 (bootstrap logger):** a minimal `Log.Logger` for startup errors before the
`IConfiguration` is available. Writes to console only.
> **No process-global state.** `AddZbSerilog` does NOT set or freeze the static
> `Log.Logger`. It passes `preserveStaticLogger: true` to `AddSerilog` so the global
> logger is left entirely untouched. This keeps the library safe for multi-host processes
> (integration tests, Aspire, test suites) — calling `AddZbSerilog` twice in the same
> process must never throw "The logger is already frozen".
>
> The optional Stage-1 **bootstrap logger** (`CreateBootstrapLogger`) — a minimal
> console-only `Log.Logger` for capturing startup exceptions before `IConfiguration` is
> available — is the **application's responsibility**, not the library's. Apps that need
> it should add this to `Program.cs` before calling `AddZbSerilog`:
> ```csharp
> Log.Logger = new LoggerConfiguration().WriteTo.Console().CreateBootstrapLogger();
> ```
**Stage 2 (application logger):** reads sinks and overrides from `IConfiguration`
**Application logger (DI):** reads sinks and overrides from `IConfiguration`
(`ReadFrom.Configuration`) and applies a set of fixed enrichers:
| Enricher | Property name | Source |
@@ -170,9 +181,9 @@ process in log events) while making the plumbing reusable.
| Project | Current state | Primary gaps | What normalizes |
|---|---|---|---|
| **OtOpcUa** | Full OTel SDK (`WithMetrics` + `WithTracing`); Prometheus `/metrics`; Serilog bootstrap; 7 instruments + 2 spans. | No `Resource` / `service.name` anywhere; no trace↔log correlation; no `SiteId`/`NodeRole` enrichers. | Call `AddZbTelemetry` (adds Resource; consolidates standard instrumentation); call `AddZbSerilog` (adds `TraceContextEnricher` + identity enrichers); migrate existing Serilog bootstrap to shared two-stage pattern. |
| **OtOpcUa** | Full OTel SDK (`WithMetrics` + `WithTracing`); Prometheus `/metrics`; Serilog bootstrap; 7 instruments + 2 spans. | No `Resource` / `service.name` anywhere; no trace↔log correlation; no `SiteId`/`NodeRole` enrichers. | Call `AddZbTelemetry` (adds Resource; consolidates standard instrumentation); call `AddZbSerilog` (adds `TraceContextEnricher` + identity enrichers); remove bespoke Serilog bootstrap (if a pre-Build bootstrap logger is wanted, add `Log.Logger = new LoggerConfiguration()...CreateBootstrapLogger();` in `Program.cs`). |
| **MxGateway** | Hand-rolled `GatewayMetrics` (13 counters / 3 histograms `ms` / 4 gauges); in-memory snapshot only — no export; MEL logging with `GatewayLogScope` correlation + `GatewayLogRedactor`; no OTel SDK. | No OTel SDK; no export; `ms` histograms diverge from OTel semconv (`s`); MEL → Serilog migration; no Resource. | Call `AddZbTelemetry` (wires OTel SDK around existing `GatewayMetrics` — finally exports); call `AddZbSerilog` (replaces MEL; re-expresses `GatewayLogScope` as `LogContext.PushProperty`; moves `GatewayLogRedactor` behind `ILogRedactor`). Duration unit convergence (`ms`→`s`) tracked in GAPS. **This is the one adoption done now.** |
| **ScadaBridge** | `OpenTelemetry.Api` ref only (dangling — CVE-patch origin, zero usage); Serilog bootstrap (`LoggerConfigurationFactory`) with `SiteId`/`NodeRole`/`NodeHostname` enrichers. | No OTel SDK; no metrics; no tracing; no export; no trace↔log correlation. ScadaBridge's enricher property names are already the target names — migration is additive. | Call `AddZbTelemetry` (adds OTel SDK + metrics + traces + export); call `AddZbSerilog` (consolidates `LoggerConfigurationFactory`; adds `TraceContextEnricher`). |
| **ScadaBridge** | `OpenTelemetry.Api` ref only (dangling — CVE-patch origin, zero usage); Serilog bootstrap (`LoggerConfigurationFactory`) with `SiteId`/`NodeRole`/`NodeHostname` enrichers. | No OTel SDK; no metrics; no tracing; no export; no trace↔log correlation. ScadaBridge's enricher property names are already the target names — migration is additive. | Call `AddZbTelemetry` (adds OTel SDK + metrics + traces + export); call `AddZbSerilog` (consolidates `LoggerConfigurationFactory`; adds `TraceContextEnricher`); if a pre-Build bootstrap logger is wanted, set `Log.Logger = new LoggerConfiguration()...CreateBootstrapLogger();` in `Program.cs`. |
> The MxGateway logging migration (`MEL → Serilog`, re-expressing `GatewayLogRedactor`
> behind `ILogRedactor`) is the **only sister-repo touch in scope for this release**. OtOpcUa