diff --git a/ZB.MOM.WW.Telemetry/README.md b/ZB.MOM.WW.Telemetry/README.md index 4656e12..54f422b 100644 --- a/ZB.MOM.WW.Telemetry/README.md +++ b/ZB.MOM.WW.Telemetry/README.md @@ -83,6 +83,10 @@ intact (not reallocated). See the `ILogRedactor` XML doc for the full contract. The same attribute set goes to metrics, traces and the OTLP log sink. +`options.ApplyConfiguration(config.GetSection(":Telemetry"))` reads the operator keys from an +app's own section — `Exporter`, `OtlpEndpoint`, `ServiceVersion`, `SiteId`, `NodeRole`, `ExportLogs`, +`ResourceAttributes:` — leaving any absent key at the code default the app set before the call. + ## Exporter options Prometheus is **always wired** for metrics regardless of the `Exporter` setting. OTLP is an @@ -156,9 +160,9 @@ backend): | Assembly | Tests | |---|---| -| `ZB.MOM.WW.Telemetry.Tests` | 35 | +| `ZB.MOM.WW.Telemetry.Tests` | 38 | | `ZB.MOM.WW.Telemetry.Serilog.Tests` | 39 | -| **Total** | **74** | +| **Total** | **77** | The log-export tests start a loopback OTLP/gRPC receiver on Kestrel (no external collector). @@ -185,7 +189,7 @@ lockstep from `Directory.Build.props`. ## Status **`0.3.0`** (scadaproj#55) is the current release on the Gitea feed: `service.version` defaults from the -entry assembly, `ResourceAttributes` for extra Resource attributes, logs follow `AddZbTelemetry`'s OTLP +entry assembly, `ResourceAttributes` for extra Resource attributes, `ApplyConfiguration` for an app's telemetry config section, logs follow `AddZbTelemetry`'s OTLP exporter, and the 0.2.1 review fixes (including the stricter OTLP endpoint check: a scheme-less `host:port` now fails at startup when `Exporter = Otlp`). Feed versions: `0.1.0`, `0.2.0`, `0.3.0` (`0.2.1` was never published). Consumer pins: see `CLAUDE.md`. Adoption history is in the component backlog: diff --git a/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry/ZbTelemetryConfigurationExtensions.cs b/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry/ZbTelemetryConfigurationExtensions.cs new file mode 100644 index 0000000..633c916 --- /dev/null +++ b/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry/ZbTelemetryConfigurationExtensions.cs @@ -0,0 +1,72 @@ +using Microsoft.Extensions.Configuration; + +namespace ZB.MOM.WW.Telemetry; + +/// +/// Reads an app's own telemetry configuration section onto , so +/// every app exposes the same operator keys under its own prefix (e.g. OtOpcUa:Telemetry, +/// MxGateway:Telemetry) without re-implementing the parsing. +/// +public static class ZbTelemetryConfigurationExtensions +{ + /// + /// Applies the keys present in ; an absent key leaves the option as the + /// caller set it, so call this after setting code defaults: + /// + /// ExporterPrometheus | Otlp, case-insensitive; an unparseable value is ignored. + /// OtlpEndpointe.g. http://collector:4317 (non-blank only). + /// ServiceVersionoverrides the entry-assembly default; an empty value omits service.version. + /// SiteId / NodeRoleResource site.id / node.role (non-blank only). + /// ExportLogstrue | false; whether OTLP also carries logs. + /// ResourceAttributes:<key>extra string Resource attributes (reserved keys are rejected at startup). + /// + /// + /// The options to update. + /// The app's telemetry section (it may be empty or missing). + /// , for chaining. + public static ZbTelemetryOptions ApplyConfiguration(this ZbTelemetryOptions options, IConfiguration section) + { + ArgumentNullException.ThrowIfNull(options); + ArgumentNullException.ThrowIfNull(section); + + if (Enum.TryParse(section["Exporter"], ignoreCase: true, out var exporter)) + { + options.Exporter = exporter; + } + + if (section["OtlpEndpoint"] is { } endpoint && !string.IsNullOrWhiteSpace(endpoint)) + { + options.OtlpEndpoint = endpoint; + } + + if (section["ServiceVersion"] is { } version) + { + options.ServiceVersion = version.Trim(); + } + + if (section["SiteId"] is { } siteId && !string.IsNullOrWhiteSpace(siteId)) + { + options.SiteId = siteId.Trim(); + } + + if (section["NodeRole"] is { } nodeRole && !string.IsNullOrWhiteSpace(nodeRole)) + { + options.NodeRole = nodeRole.Trim(); + } + + if (bool.TryParse(section["ExportLogs"], out var exportLogs)) + { + options.ExportLogs = exportLogs; + } + + foreach (var child in section.GetSection("ResourceAttributes").GetChildren()) + { + if (child.Value is { } value) + { + options.ResourceAttributes[child.Key] = value; + } + } + + return options; + } +} diff --git a/ZB.MOM.WW.Telemetry/tests/ZB.MOM.WW.Telemetry.Tests/ApplyConfigurationTests.cs b/ZB.MOM.WW.Telemetry/tests/ZB.MOM.WW.Telemetry.Tests/ApplyConfigurationTests.cs new file mode 100644 index 0000000..5136db5 --- /dev/null +++ b/ZB.MOM.WW.Telemetry/tests/ZB.MOM.WW.Telemetry.Tests/ApplyConfigurationTests.cs @@ -0,0 +1,62 @@ +using Microsoft.Extensions.Configuration; +using ZB.MOM.WW.Telemetry; + +namespace ZB.MOM.WW.Telemetry.Tests; + +public sealed class ApplyConfigurationTests +{ + private static IConfiguration Section(Dictionary values) => + new ConfigurationBuilder().AddInMemoryCollection(values).Build().GetSection("App:Telemetry"); + + [Fact] + public void Applies_every_key() + { + var o = new ZbTelemetryOptions { ServiceName = "x" }.ApplyConfiguration(Section(new() + { + ["App:Telemetry:Exporter"] = "otlp", + ["App:Telemetry:OtlpEndpoint"] = "http://collector:4317", + ["App:Telemetry:ServiceVersion"] = "5.0.0", + ["App:Telemetry:SiteId"] = " plant-1 ", + ["App:Telemetry:NodeRole"] = "standalone", + ["App:Telemetry:ExportLogs"] = "false", + ["App:Telemetry:ResourceAttributes:deployment.environment.name"] = "dev", + })); + + Assert.Equal(ZbExporter.Otlp, o.Exporter); + Assert.Equal("http://collector:4317", o.OtlpEndpoint); + Assert.Equal("5.0.0", o.ServiceVersion); + Assert.Equal("plant-1", o.SiteId); + Assert.Equal("standalone", o.NodeRole); + Assert.False(o.ExportLogs); + Assert.Equal("dev", o.ResourceAttributes["deployment.environment.name"]); + } + + [Fact] + public void Absent_or_blank_keys_keep_code_defaults() + { + var o = new ZbTelemetryOptions { ServiceName = "x", SiteId = "code-site", NodeRole = "code-role" } + .ApplyConfiguration(Section(new() + { + ["App:Telemetry:SiteId"] = " ", + ["App:Telemetry:Exporter"] = "not-an-exporter", + })); + + Assert.Equal("code-site", o.SiteId); + Assert.Equal("code-role", o.NodeRole); + Assert.Equal(ZbExporter.Prometheus, o.Exporter); + Assert.Null(o.OtlpEndpoint); + Assert.Null(o.ServiceVersion); + Assert.True(o.ExportLogs); + Assert.Empty(o.ResourceAttributes); + } + + [Fact] + public void Empty_ServiceVersion_omits_the_attribute() + { + var o = new ZbTelemetryOptions { ServiceName = "x" } + .ApplyConfiguration(Section(new() { ["App:Telemetry:ServiceVersion"] = "" })); + + Assert.Equal("", o.ServiceVersion); + Assert.False(ZbResource.BuildAttributes(o, "1.0.0+abc").ContainsKey("service.version")); + } +}