Joseph Doherty
8311912f40
- NuGet metadata: expanded Description and PackageTags on both library csproj files (opentelemetry;observability;metrics;tracing;prometheus;otlp;... / serilog;logging;...) - Full dotnet test: 7 (Telemetry) + 12 (Serilog) = 19 tests, all green - dotnet pack: ZB.MOM.WW.Telemetry.0.1.0.nupkg + ZB.MOM.WW.Telemetry.Serilog.0.1.0.nupkg (artifacts/ gitignored, not committed) - ZB.MOM.WW.Telemetry/README.md: overview, 2 packages, unifying hinge prose, exporter options, OTel signals + trace-log correlation, test/pack commands, status - ZB.MOM.WW.Telemetry/CLAUDE.md: package responsibilities, consumer matrix, build/test/pack commands, status + pointers to components/observability/ - components/README.md: Observability row added to component registry table - CLAUDE.md: Telemetry row added to component-normalization table; intro count updated to four shared libs; observability prose paragraph added (MxGateway logging adoption noted) - upcoming.md: Observability item ticked done, pointing at components/observability/ and ZB.MOM.WW.Telemetry; MxGateway MEL->Serilog adoption noted - components/observability/README.md: status updated to Built @ 0.1.0, library build/pack commands added, MxGateway adoption row updated
75 lines
3.9 KiB
Markdown
75 lines
3.9 KiB
Markdown
# ZB.MOM.WW.Telemetry
|
|
|
|
Observability libraries for the **ZB.MOM.WW SCADA family** (OtOpcUa, MxAccessGateway, ScadaBridge). These are **libraries, not a service** — each package is linked directly into the consuming application at build time. There is no central telemetry process; instrumentation runs in-process alongside the application.
|
|
|
|
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. MxAccessGateway logging adopted (MEL → Serilog migration done on its own branch). OtOpcUa and ScadaBridge telemetry adoption is follow-on.** Adoption tracked in `~/Desktop/scadaproj/components/observability/GAPS.md`.
|
|
|
|
---
|
|
|
|
## Packages
|
|
|
|
| Package | Responsibilities | Key Dependencies |
|
|
|---|---|---|
|
|
| `ZB.MOM.WW.Telemetry` | `AddZbTelemetry` — wires OTel SDK (metrics + tracing), populates shared Resource (`service.name`, `service.namespace`, `service.version`, `site.id`, `node.role`, `host.name`), registers caller-supplied Meters/ActivitySources, adds standard instrumentation (ASP.NET Core, HttpClient, gRPC client, runtime, process), Prometheus always-on exporter, OTLP additive overlay. `app.MapZbMetrics()` — mounts `/metrics`. `ZbTelemetryOptions` — the single options object shared by both packages. | `Microsoft.AspNetCore.App` (framework ref), `OpenTelemetry.*` stack |
|
|
| `ZB.MOM.WW.Telemetry.Serilog` | `AddZbSerilog` — shared two-stage Serilog bootstrap: `ReadFrom.Configuration`-driven sinks, `MinimumLevel.Is(Information)` default (config-overridable), `SiteId`/`NodeRole`/`NodeHostname` enrichers from `ZbTelemetryOptions`, `TraceContextEnricher` (writes `trace_id`/`span_id` from `Activity.Current`), `ILogRedactor` seam (per-project sensitive-field redaction via `RedactionEnricher`). Does NOT freeze `Log.Logger` — safe for multi-host/test scenarios. | `ZB.MOM.WW.Telemetry`, `Serilog.*` stack |
|
|
|
|
---
|
|
|
|
## Consumer matrix
|
|
|
|
| Consumer | `ZB.MOM.WW.Telemetry` (core) | `ZB.MOM.WW.Telemetry.Serilog` |
|
|
|---|:---:|:---:|
|
|
| **OtOpcUa** | yes (after adoption) | yes (after adoption) |
|
|
| **MxAccessGateway** | yes (after adoption) | yes (MEL → Serilog adopted now) |
|
|
| **ScadaBridge** | yes (after adoption) | yes (after adoption) |
|
|
|
|
MxAccessGateway's logging adoption is the one in-pass migration. Full metrics/tracing wiring
|
|
for all three apps is follow-on.
|
|
|
|
---
|
|
|
|
## Build, test, and pack commands
|
|
|
|
```bash
|
|
# From ZB.MOM.WW.Telemetry/
|
|
|
|
# Build
|
|
dotnet build ZB.MOM.WW.Telemetry.slnx
|
|
dotnet build ZB.MOM.WW.Telemetry.slnx -c Release
|
|
|
|
# Test (no external dependencies — no running OTel collector, no Serilog backend required)
|
|
dotnet test ZB.MOM.WW.Telemetry.slnx
|
|
|
|
# Pack (two .nupkg files land in artifacts/)
|
|
dotnet pack ZB.MOM.WW.Telemetry.slnx -c Release -o ./artifacts
|
|
```
|
|
|
|
All test assemblies run offline:
|
|
|
|
| Assembly | Tests |
|
|
|---|---|
|
|
| `ZB.MOM.WW.Telemetry.Tests` | 7 |
|
|
| `ZB.MOM.WW.Telemetry.Serilog.Tests` | 12 |
|
|
| **Total** | **19** |
|
|
|
|
`GeneratePackageOnBuild` is off — pack explicitly with the command above.
|
|
|
|
---
|
|
|
|
## Status
|
|
|
|
Built at **0.1.0** and published to the Gitea NuGet feed. MxAccessGateway logging (MEL → Serilog)
|
|
adopted on its own branch. **OtOpcUa and ScadaBridge telemetry adoption not yet started** —
|
|
tracked in the component backlog:
|
|
|
|
- `~/Desktop/scadaproj/components/observability/GAPS.md` — adoption order, effort, and risk
|
|
|
|
Design documentation:
|
|
|
|
- `~/Desktop/scadaproj/components/observability/spec/SPEC.md` — normalized observability target
|
|
- `~/Desktop/scadaproj/components/observability/spec/METRIC-CONVENTIONS.md` — metric naming reference
|
|
- `~/Desktop/scadaproj/components/observability/shared-contract/ZB.MOM.WW.Telemetry.md` — proposed shared-library API
|
|
- `~/Desktop/scadaproj/components/observability/current-state/` — per-project current state (code-verified)
|