diff --git a/CLAUDE.md b/CLAUDE.md index a86983d..14fb25a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -162,7 +162,7 @@ each project's **code-verified current state**, and the **gaps** between. See | Auth (login / identity / authz) | **2026-11-09: source at `0.4.4`, UNPUBLISHED** (0.4.2 typed `ApiKeyPepperUnavailableException`; 0.4.3 Sqlite 10.0.13; 0.4.4 user-bind proves the bound account = the entry whose groups it returns (#40), SQL Server key ids case-exact, `ApiKeyFailure.StoreUnavailable`) — live-verify vs real AD before publishing (scadaproj#51). Adopted. Feed carries **`0.4.1`** (2026-10-01; 0.4.0 the same day; opt-in user bind) — **all four apps pin `0.4.1` on their default branches since 2026-11-09** (scadaproj#5: OtOpcUa `1ecd01d3`, ScadaBridge `37fcd296`, mxgw `ace12f81`, HistorianGateway `0d06483`; `BindMode` left at `ServiceAccount`; NOT deployed — wonder boxes still run `0.3.0` builds). History below refers to the earlier `0.3.0` pins. **All four apps pin `0.3.0`** (2026-09-03, all on their default branch and pushed — and all four are DEPLOYED at those tips on DEV vd03 and QA vq03/vq04 since 2026-09-10: OtOpcUa `b8b4c18f`, mxgw `4f931e4`, HistorianGateway `d8d890c`; ScadaBridge already had it on `main` via the `inbound-api-key-shared-store` work, `e45c4af9`). **0.4.0 (2026-10-01) — opt-in LDAP user bind:** adds `LdapOptions.BindMode` (`ServiceAccount` default | `User`), `UserBindTemplate` and `AcceptDomainQualifiedNames`; in `User` mode `LdapAuthService` binds as the signing-in user and reads their own groups on the same connection, so no service account is needed. Bind failures map to `BadCredentials` (bad password, unusable name, or bind result 49) or `GroupLookupFailed` (zero/multiple entries or no groups after a good bind), other bind/connect/search errors fail over to the next endpoint, and `ServiceAccount` stays the default so no existing consumer needs to change. **0.4.1** fixes the review findings: `Username` is canonicalised from the entry's `UserNameAttribute`, empty passwords are refused in both bind modes (a `ServiceAccount`-mode behaviour change), and the docs prefer the down-level `EXAMPLE\{0}` template over UPN. First consumer: BTDB Manager; ScadaBridge/HistorianGateway/OtOpcUa/MxAccessGateway stay on `0.3.0` until they move to AD. `0.2.1` is a functional fix, not housekeeping — `0.1.5` cannot log in against an AD domain root at all. `FallbackServers` (0.2.0) live-gated on the redundant local GLAuth pair. Version narrative, consumer matrix, `tools/LdapProbe`: [`ZB.MOM.WW.Auth/CLAUDE.md`](ZB.MOM.WW.Auth/CLAUDE.md). | Shared `ZB.MOM.WW.Auth` lib | [`components/auth/`](components/auth/) | [`ZB.MOM.WW.Auth/`](ZB.MOM.WW.Auth/) | | UI Theme (layout / tokens / components) | **2026-11-09: all five consumers pin `0.5.0` on their default branches (scadaproj#9; not deployed, no browser check yet); **`0.5.3` published 2026-11-12** (TechButton `disabled`, nav-state WeakSet, opt-in `ThemeShell ScrollNav`; 0.5.3 shell `100dvh` fill, #10; no consumer pins it yet — ScadaBridge#61 is first).** Adopted. Feed `0.2.0`–`0.5.0` + `0.5.3`; **five** consumers (the ignitionoee router joined), all on `0.4.1` and pushed (2026-08-11); Every deployed wonder box (DEV vd03 + QA vq03/vq04) runs its repo tip as of 2026-09-10, so the deployed Theme is 0.4.1 everywhere. **On bump, TRIM the local `.btn` block, don't delete it** — mxgw's carried more than sizing. Narrative: [`ZB.MOM.WW.Theme/CLAUDE.md`](ZB.MOM.WW.Theme/CLAUDE.md). | Shared `ZB.MOM.WW.Theme` RCL | [`components/ui-theme/`](components/ui-theme/) | [`ZB.MOM.WW.Theme/`](ZB.MOM.WW.Theme/) | | Health (readiness / liveness / active-node) | **Adopted** — lib `0.3.0`, all 4 apps reference it + wire `MapZbHealth`. `0.2.1`/`0.3.0` changed the active tier's behaviour (standby now answers **503**; active = oldest `Up` member via `ClusterActiveNode`, not `RoleLeader` — the two diverge after any restart), and both Akka apps' private copies were deleted in its favour (merged + pushed). Narrative: [`ZB.MOM.WW.Health/CLAUDE.md`](ZB.MOM.WW.Health/CLAUDE.md). | Shared `ZB.MOM.WW.Health` lib | [`components/health/`](components/health/) | [`ZB.MOM.WW.Health/`](ZB.MOM.WW.Health/) | -| Observability (metrics / traces / logs) | **Adopted** (libs `0.1.0`, on the feed; **all 4 apps** call `AddZbTelemetry`; `AddZbSerilog` in all but ScadaBridge, which keeps its own factory by design) | Shared `ZB.MOM.WW.Telemetry` lib + `.Serilog` | [`components/observability/`](components/observability/) | [`ZB.MOM.WW.Telemetry/`](ZB.MOM.WW.Telemetry/) | +| Observability (metrics / traces / logs) | **Adopted** — **`0.2.0` published 2026-11-12** (feed `0.1.0` + `0.2.0`; source at `0.2.1`, unpublished). **All 4 apps** call `AddZbTelemetry` **and** `AddZbSerilog`: ScadaBridge switched 2026-11-12 on `0.2.0` (#94, `main` `2d2e9f35`, governor + `ConfigureLogger` hooks); the other three stay on `0.1.0`, source-compatible. Narrative: [`ZB.MOM.WW.Telemetry/CLAUDE.md`](ZB.MOM.WW.Telemetry/CLAUDE.md). | Shared `ZB.MOM.WW.Telemetry` lib + `.Serilog` | [`components/observability/`](components/observability/) | [`ZB.MOM.WW.Telemetry/`](ZB.MOM.WW.Telemetry/) | | Config + validation (options / startup validation) | Adopted (lib `0.1.0`, on the feed; **all 4 apps**, pushed — the "local only / not yet pushed" caveat was stale) | Shared `ZB.MOM.WW.Configuration` lib | [`components/configuration/`](components/configuration/) | [`ZB.MOM.WW.Configuration/`](ZB.MOM.WW.Configuration/) | | Audit (event model + writer seam) | Adopted (lib `0.1.0`, on the feed; **all 4 apps**, pushed to origin) | Shared `ZB.MOM.WW.Audit` lib | [`components/audit/`](components/audit/) | [`ZB.MOM.WW.Audit/`](ZB.MOM.WW.Audit/) | | Galaxy Repository (object-hierarchy SQL browse + gRPC service) | **Adopted** (feed `0.1.0` + `0.2.0`; consumed at `0.2.0` by HistorianGateway **and mxaccessgw**, whose Server wires `AddZbGalaxyRepository` — verified 2026-07-18; the prior "mxaccessgw adoption is a follow-on" claim was stale) | Shared `ZB.MOM.WW.GalaxyRepository` lib | _(design in histsdk + design doc 2026-06-23)_ | [`ZB.MOM.WW.GalaxyRepository/`](ZB.MOM.WW.GalaxyRepository/) | diff --git a/ZB.MOM.WW.Telemetry/CLAUDE.md b/ZB.MOM.WW.Telemetry/CLAUDE.md index 89d5ea1..f129e54 100644 --- a/ZB.MOM.WW.Telemetry/CLAUDE.md +++ b/ZB.MOM.WW.Telemetry/CLAUDE.md @@ -6,7 +6,7 @@ Observability libraries for the **ZB.MOM.WW SCADA family** (OtOpcUa, MxAccessGat The library normalizes the three-project observability surface: a shared OpenTelemetry Resource driven by a single identity triple (`service.name` / `site.id` / `node.role`), standard instrumentation wiring, Prometheus and OTLP export, and a Serilog bootstrap with enrichers and `TraceContextEnricher` for trace↔log correlation. -**Built at 0.1.0, published to the Gitea NuGet feed, and adopted across all three apps on 2026-06-01** (branch `feat/adopt-zb-telemetry` per repo, behaviour-preserving). MxAccessGateway's MEL→Serilog migration + metrics export both landed in this pass — they were *not* actually done beforehand despite the earlier claim. ScadaBridge keeps its `LoggerConfigurationFactory` (min-level governance) and only adds the shared `TraceContextEnricher`; it does not call `AddZbSerilog`. Per-repo result + deferred follow-ons tracked in `~/Desktop/scadaproj/components/observability/GAPS.md`. +**Built at 0.1.0, published to the Gitea NuGet feed, and adopted across all three apps on 2026-06-01** (branch `feat/adopt-zb-telemetry` per repo, behaviour-preserving). MxAccessGateway's MEL→Serilog migration + metrics export both landed in this pass — they were *not* actually done beforehand despite the earlier claim. ScadaBridge kept its own `LoggerConfigurationFactory` until **2026-11-12**, when it switched to `AddZbSerilog` 0.2.0 (ScadaBridge#94). Per-repo result + deferred follow-ons tracked in `~/Desktop/scadaproj/components/observability/GAPS.md`. --- @@ -25,12 +25,12 @@ The library normalizes the three-project observability surface: a shared OpenTel |---|:---:|:---:| | **OtOpcUa** | ✅ adopted | ✅ adopted (`AddZbSerilog`) | | **MxAccessGateway** | ✅ adopted (`GatewayMetrics` exported) | ✅ adopted (MEL→Serilog migrated in this pass) | -| **ScadaBridge** | ✅ adopted (both roots) | ⚠️ referenced for `TraceContextEnricher` only — keeps `LoggerConfigurationFactory`, does **not** call `AddZbSerilog` | +| **ScadaBridge** | ✅ adopted (both roots) | ✅ `AddZbSerilog` **0.2.0** (2026-11-12, ScadaBridge#94, `main` `2d2e9f35`) — `MinimumLevelGovernor` + `ConfigureLogger` (standby filter); run on a pre-host builder so the static `Log.Logger` stays the one process logger | | **HistorianGateway** | ✅ adopted | ✅ adopted (`AddZbSerilog`) | -All three adopted on 2026-06-01 (branch `feat/adopt-zb-telemetry` per repo); HistorianGateway adopted since. All four pin both packages at `0.1.0` on their origin default branches (verified 2026-11-09). ScadaBridge's logging -deviates: it keeps its own `LoggerConfigurationFactory` (min-level governance contract) and only -adds the shared `TraceContextEnricher`. See `components/observability/GAPS.md` for the full result. +All three adopted on 2026-06-01 (branch `feat/adopt-zb-telemetry` per repo); HistorianGateway adopted since. OtOpcUa, MxAccessGateway and HistorianGateway pin both packages at `0.1.0` on their origin default branches +(verified 2026-11-09; their `AddZbSerilog(o => …)` call sites are source-compatible with 0.2.0 — the new overload is +additive). ScadaBridge pins **`0.2.0`** since 2026-11-12. See `components/observability/GAPS.md` for the full result. --- @@ -71,7 +71,11 @@ endpoint must be `http`/`https` with a host (`collector:4317` is now rejected) a `AddZbTelemetry(services, options)` overload validates `ServiceName` + endpoint like the lambda overloads (011). **Behaviour change:** a scheme-less OTLP endpoint that previously passed validation now throws at startup. -**`0.2.0` (2026-11-09, scadaproj#12) — built, NOT published** (feed carries `0.1.0` only). Additive: +**`0.2.0` (2026-11-09, scadaproj#12) — PUBLISHED 2026-11-12** (both packages, packed from `01c6dc1` — the +0.2.0 code plus the corrected RepositoryUrl, i.e. before the 0.2.1 commit `1786bab`; 12 + 30 tests green in Release). +SHA256: `ZB.MOM.WW.Telemetry.0.2.0.nupkg` `71749cb3c34a0d0aba3eca43a6c12398b427f494e8c4c6f216db0be7d3ab40dc`, +`ZB.MOM.WW.Telemetry.Serilog.0.2.0.nupkg` `2aef391e7ab28061c5b3365c62c73e5c972ba8bcecd88bd0e0471550cfcc40c0` +(feed download matches the local pack). First consumer: ScadaBridge (#94). Additive: a new `AddZbSerilog(builder, configure, configureSerilog)` overload taking `ZbSerilogOptions` — `MinimumLevelGovernor` (`Func`, applied with `MinimumLevel.Is` AFTER `ReadFrom.Configuration`, so an app-owned key outranks `Serilog:MinimumLevel`; `null` defers to diff --git a/components/observability/GAPS.md b/components/observability/GAPS.md index 4fd8e4d..8a75ac1 100644 --- a/components/observability/GAPS.md +++ b/components/observability/GAPS.md @@ -11,9 +11,9 @@ reach the shared `ZB.MOM.WW.Telemetry` library. Status legend: ⛔ gap · 🟡 p > **✅ ADOPTED — verified 2026-07-18.** `ZB.MOM.WW.Telemetry` + `.Serilog` `0.1.0` are on the Gitea > feed and **all four apps reference both and call `AddZbTelemetry`** (Resource + standard > instrumentation + Prometheus `/metrics`). Logging: OtOpcUa, MxAccessGateway and **HistorianGateway** -> (a fourth consumer this file predates) use `AddZbSerilog`; ScadaBridge deliberately keeps its own -> `LoggerConfigurationFactory` for min-level governance and adds only the shared `TraceContextEnricher` -> — that split is by design, not a gap. Library suite: **34 tests**, green 2026-07-18. +> (a fourth consumer this file predates) use `AddZbSerilog`; **ScadaBridge joined them 2026-11-12** +> (ScadaBridge#94, `main` `2d2e9f35`) on Telemetry(.Serilog) **`0.2.0`** — published 2026-11-12 — via its +> `MinimumLevelGovernor` + `ConfigureLogger` hooks; `LoggerConfigurationFactory` is deleted. Library suite: **34 tests**, green 2026-07-18. > > **The `⛔ not set` divergence tables below are the pre-adoption 2026-06-01 snapshot** — the §1 > Resource-attribute gaps they describe are what `AddZbTelemetry` closed. Read them as the @@ -218,7 +218,7 @@ sister apps in one pass, behaviour-preserving. Each adoption landed on a per-rep | Repo | `AddZbTelemetry` (Resource + std instrumentation + Prometheus) | `/metrics` | Logging | Meter (unchanged) | |---|---|---|---|---| | **OtOpcUa** | ✅ replaced hand-rolled `ObservabilityExtensions` | ✅ `/metrics` (path unchanged) | ✅ `AddZbSerilog` (sinks moved to `appsettings`; `LogContextEnricher` kept) | `ZB.MOM.WW.OtOpcUa` | -| **ScadaBridge** | ✅ added in `BindSharedOptions` (both Central + Site roots) | ✅ Central; mapped on Site too (see follow-on) | ⚠️ **kept `LoggerConfigurationFactory`** + added shared `TraceContextEnricher` — did **not** adopt `AddZbSerilog` | (none yet; #9) | +| **ScadaBridge** | ✅ added in `BindSharedOptions` (both Central + Site roots) | ✅ Central; mapped on Site too (see follow-on) | ✅ `AddZbSerilog` (0.2.0, 2026-11-12, ScadaBridge#94) with `MinimumLevelGovernor` + `ConfigureLogger`; `LoggerConfigurationFactory` deleted | (none yet; #9) | | **MxAccessGateway** | ✅ exports existing `GatewayMetrics` | ✅ new `/metrics` | ✅ MEL→`AddZbSerilog`; `GatewayLogRedactor` exposed via `ILogRedactor` seam (`GatewayLogRedactorSeam`); `GatewayLogScope`/middleware kept as-is | `MxGateway.Server` (name + `ms` units unchanged) | ### Accepted scope decisions (deviations from the original backlog) @@ -230,10 +230,10 @@ sister apps in one pass, behaviour-preserving. Each adoption landed on a per-rep precedence and silently drop the knob. So ScadaBridge keeps the factory and only **adds the shared `TraceContextEnricher`** to it — gaining trace↔log correlation without regressing the contract. Full `AddZbSerilog` adoption for ScadaBridge would first require teaching the shared bootstrap to accept a - caller-supplied minimum-level governance hook (→ #12). **Library half landed in Telemetry `0.2.0` (unpublished, 2026-11-09):** `AddZbSerilog(builder, + caller-supplied minimum-level governance hook (→ #12). **Library half landed in Telemetry `0.2.0` (built 2026-11-09, published 2026-11-12):** `AddZbSerilog(builder, configure, s => { s.MinimumLevelGovernor = …; s.ConfigureLogger = …; })` — the governor runs after - `ReadFrom.Configuration`, `ConfigureLogger` carries the standby `active-node` filter. ScadaBridge's switch is - the remaining follow-on in that repo. + `ReadFrom.Configuration`, `ConfigureLogger` carries the standby `active-node` filter. **ScadaBridge switched + 2026-11-12 (ScadaBridge#94, `main` `2d2e9f35`)** — this deviation is closed. - **MxGateway keeps `GatewayLogScope` + request-logging middleware as-is.** The Serilog MEL provider captures MEL `BeginScope` dictionaries as structured properties, so the scope/correlation code keeps producing the same properties under Serilog. Only the provider swap + the `ILogRedactor` adapter were