feat(telemetry): 0.3.0 ApplyConfiguration reads an app's telemetry section (#55)

Exporter, OtlpEndpoint, ServiceVersion, SiteId, NodeRole, ExportLogs and
ResourceAttributes:<key> from <App>:Telemetry, absent keys keep code defaults, so
the four apps stop re-implementing the exporter parse and gain the identity keys.

Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
This commit is contained in:
Joseph Doherty
2026-11-12 21:03:29 -05:00
parent cfc7168ace
commit 2011c8d6b9
3 changed files with 141 additions and 3 deletions
+7 -3
View File
@@ -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("<App>:Telemetry"))` reads the operator keys from an
app's own section — `Exporter`, `OtlpEndpoint`, `ServiceVersion`, `SiteId`, `NodeRole`, `ExportLogs`,
`ResourceAttributes:<key>` — 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:
@@ -0,0 +1,72 @@
using Microsoft.Extensions.Configuration;
namespace ZB.MOM.WW.Telemetry;
/// <summary>
/// Reads an app's own telemetry configuration section onto <see cref="ZbTelemetryOptions"/>, so
/// every app exposes the same operator keys under its own prefix (e.g. <c>OtOpcUa:Telemetry</c>,
/// <c>MxGateway:Telemetry</c>) without re-implementing the parsing.
/// </summary>
public static class ZbTelemetryConfigurationExtensions
{
/// <summary>
/// Applies the keys present in <paramref name="section"/>; an absent key leaves the option as the
/// caller set it, so call this after setting code defaults:
/// <list type="table">
/// <item><term><c>Exporter</c></term><description><c>Prometheus</c> | <c>Otlp</c>, case-insensitive; an unparseable value is ignored.</description></item>
/// <item><term><c>OtlpEndpoint</c></term><description>e.g. <c>http://collector:4317</c> (non-blank only).</description></item>
/// <item><term><c>ServiceVersion</c></term><description>overrides the entry-assembly default; an empty value omits <c>service.version</c>.</description></item>
/// <item><term><c>SiteId</c> / <c>NodeRole</c></term><description>Resource <c>site.id</c> / <c>node.role</c> (non-blank only).</description></item>
/// <item><term><c>ExportLogs</c></term><description><c>true</c> | <c>false</c>; whether OTLP also carries logs.</description></item>
/// <item><term><c>ResourceAttributes:&lt;key&gt;</c></term><description>extra string Resource attributes (reserved keys are rejected at startup).</description></item>
/// </list>
/// </summary>
/// <param name="options">The options to update.</param>
/// <param name="section">The app's telemetry section (it may be empty or missing).</param>
/// <returns><paramref name="options"/>, for chaining.</returns>
public static ZbTelemetryOptions ApplyConfiguration(this ZbTelemetryOptions options, IConfiguration section)
{
ArgumentNullException.ThrowIfNull(options);
ArgumentNullException.ThrowIfNull(section);
if (Enum.TryParse<ZbExporter>(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;
}
}
@@ -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<string, string?> 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"));
}
}