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/shared-contract/ZB.MOM.WW.Telemetry.md
+22 -12
View File
@@ -148,22 +148,30 @@ public static class ZbMetricsEndpointExtensions
```csharp
namespace ZB.MOM.WW.Telemetry.Serilog;
/// Extension point for configuring the Serilog two-stage bootstrap on an IHostApplicationBuilder.
/// Extension point for registering the Serilog application logger in DI on an IHostApplicationBuilder.
public static class ZbSerilogExtensions
{
/// Two-stage Serilog bootstrap:
/// Stage 1 — minimal console-only bootstrap logger (for startup errors before IConfiguration).
/// Stage 2 — application logger wired from IConfiguration (ReadFrom.Configuration reads
/// Serilog:WriteTo sinks + Serilog:MinimumLevel from "Serilog:MinimumLevel") with
/// fixed enrichers: SiteId + NodeRole from ZbTelemetryOptions; NodeHostname from
/// Environment.MachineName (auto — not a caller-supplied option); TraceContextEnricher;
/// and RedactionEnricher (applied only when ILogRedactor is registered).
/// Registers the Serilog application logger in DI. Wires configuration-driven sinks
/// (ReadFrom.Configuration reads Serilog:WriteTo sinks + Serilog:MinimumLevel) with
/// fixed enrichers: SiteId + NodeRole from ZbTelemetryOptions; NodeHostname from
/// Environment.MachineName (auto — not a caller-supplied option); TraceContextEnricher;
/// and RedactionEnricher (applied only when ILogRedactor is registered).
///
/// MinimumLevel: AddZbSerilog reads "Serilog:MinimumLevel" from IConfiguration. Callers that
/// bind MinimumLevel from a different config key (e.g. ScadaBridge's
/// "ScadaBridge:Logging:MinimumLevel") apply that override themselves before or after
/// calling AddZbSerilog — this remains per-project and AddZbSerilog does not read it.
///
/// IMPORTANT — no process-global state: AddZbSerilog does NOT set Log.Logger. It passes
/// preserveStaticLogger: true to AddSerilog so the static logger is left untouched.
/// This makes AddZbSerilog safe to call multiple times in one process (integration tests,
/// multi-host apps) without hitting "The logger is already frozen".
///
/// Apps that need a pre-Build() bootstrap logger (for startup exceptions before IConfiguration
/// is available) should set Log.Logger themselves in Program.cs:
/// Log.Logger = new LoggerConfiguration().WriteTo.Console().CreateBootstrapLogger();
/// That is an application-level decision — not done by this library.
///
/// OTel log export is wired automatically: logs flow through the OTel pipeline with the same
/// Resource as the metrics and traces (all three signals correlated in a backend).
///
@@ -247,10 +255,12 @@ The net48 x86 mxaccessgw worker is excluded from both packages. Its `IWorkerLogg
(`Directory.Packages.props`).
3. **`RedactionEnricher` DI timing:** `RedactionEnricher` resolves `ILogRedactor` from
`IServiceProvider` on first use (lazy, to avoid a circular-DI problem during Serilog's
two-stage bootstrap). Validate that the service provider is fully built by the time the
first post-startup log event fires. If MxGateway's `GatewayLogRedactor` has dependencies
that are not available at stage-1 bootstrap time, the lazy-resolve pattern protects it.
`IServiceProvider` on first use (lazy, to avoid a circular-DI problem at host-build time).
Validate that the service provider is fully built by the time the first post-startup log
event fires. If MxGateway's `GatewayLogRedactor` has dependencies that are not yet
available when the DI container is being composed, the lazy-resolve pattern protects it.
(Note: the library no longer sets a Stage-1 bootstrap logger, so there is no Stage-1 vs.
Stage-2 logger lifetime to reason about — only the single DI-registered application logger.)
4. **`SiteId` / `NodeRole` null handling:** `AddZbTelemetry` and `AddZbSerilog` silently
omit null `SiteId`/`NodeRole` from the Resource and enricher set. Confirm this is the
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