diff --git a/ZB.MOM.WW.Telemetry/Directory.Build.props b/ZB.MOM.WW.Telemetry/Directory.Build.props index 95c45a0..3ce42a8 100644 --- a/ZB.MOM.WW.Telemetry/Directory.Build.props +++ b/ZB.MOM.WW.Telemetry/Directory.Build.props @@ -5,7 +5,7 @@ enable enable latest - 0.2.1 + 0.3.0 true diff --git a/ZB.MOM.WW.Telemetry/README.md b/ZB.MOM.WW.Telemetry/README.md index b8bce54..4656e12 100644 --- a/ZB.MOM.WW.Telemetry/README.md +++ b/ZB.MOM.WW.Telemetry/README.md @@ -49,7 +49,7 @@ follow-on (tracked in `components/observability/GAPS.md`). |---|---| | **Metrics** | App Meters (via `options.Meters[]`) + standard: ASP.NET Core, HttpClient, .NET runtime, process. Exported via Prometheus (always on) with OTLP as an additive overlay. | | **Traces** | App ActivitySources (via `options.ActivitySources[]`) + standard: ASP.NET Core, HttpClient, gRPC client. Exported via OTLP when `Exporter = ZbExporter.Otlp`. | -| **Logs** | Wired by `AddZbSerilog` (companion call). Serilog is used as the log sink; logs are bridged to OpenTelemetry via `Serilog.Sinks.OpenTelemetry` when configured. | +| **Logs** | Wired by `AddZbSerilog` (companion call). Serilog is used as the log sink; logs are bridged to OpenTelemetry via `Serilog.Sinks.OpenTelemetry` when OTLP is selected. **0.3.0+:** the OTLP log sink follows the `AddZbTelemetry` registration in the same container, so `Exporter = Otlp` on `AddZbTelemetry` alone sends logs to the same endpoint with the same Resource (`ExportLogs = false` opts out). Options passed to `AddZbSerilog` that select OTLP themselves still win (for a logger built outside the host container, e.g. ScadaBridge). | Trace↔log correlation is automatic: `TraceContextEnricher` reads `Activity.Current` for each log event and attaches `trace_id` and `span_id`, so log events produced inside a traced request @@ -71,6 +71,18 @@ intact (not reallocated). See the `ILogRedactor` XML doc for the full contract. --- +## Resource identity (0.3.0+) + +| Attribute | Source | +|---|---| +| `service.name` / `service.namespace` | `ServiceName` (required) / `ServiceNamespace` (default `ZB.MOM.WW`) | +| `service.version` | `ServiceVersion`; **`null` (default) = the entry assembly's `AssemblyInformationalVersion`** (the family apps stamp the git SHA there), `""` = omit, any other value = override | +| `site.id` / `node.role` | `SiteId` / `NodeRole` (omitted when null/empty) | +| `service.instance.id` / `host.name` | computed: `MachineName:ProcessId` / `MachineName` | +| anything else | `ResourceAttributes` (e.g. `["otopcua.cluster.id"] = "c1"`); the keys above are reserved and rejected at startup | + +The same attribute set goes to metrics, traces and the OTLP log sink. + ## Exporter options Prometheus is **always wired** for metrics regardless of the `Exporter` setting. OTLP is an @@ -144,9 +156,11 @@ backend): | Assembly | Tests | |---|---| -| `ZB.MOM.WW.Telemetry.Tests` | 12 | -| `ZB.MOM.WW.Telemetry.Serilog.Tests` | 30 | -| **Total** | **42** | +| `ZB.MOM.WW.Telemetry.Tests` | 35 | +| `ZB.MOM.WW.Telemetry.Serilog.Tests` | 39 | +| **Total** | **74** | + +The log-export tests start a loopback OTLP/gRPC receiver on Kestrel (no external collector). --- @@ -159,8 +173,8 @@ dotnet pack ZB.MOM.WW.Telemetry.slnx -c Release -o ./artifacts Produces two `.nupkg` files in `artifacts/`: ``` -ZB.MOM.WW.Telemetry.0.2.0.nupkg -ZB.MOM.WW.Telemetry.Serilog.0.2.0.nupkg +ZB.MOM.WW.Telemetry.0.3.0.nupkg +ZB.MOM.WW.Telemetry.Serilog.0.3.0.nupkg ``` `GeneratePackageOnBuild` is off — pack explicitly as above. Both packages are versioned @@ -170,12 +184,11 @@ lockstep from `Directory.Build.props`. ## Status -**`0.1.0` is on the Gitea feed and adopted by all four apps** (OtOpcUa, MxAccessGateway, ScadaBridge, -HistorianGateway): each pins `ZB.MOM.WW.Telemetry` + `ZB.MOM.WW.Telemetry.Serilog` `0.1.0` and calls -`AddZbTelemetry`; all but ScadaBridge call `AddZbSerilog` (ScadaBridge keeps its own -`LoggerConfigurationFactory` and adds only `TraceContextEnricher`). Verified against each repo's origin default -branch 2026-11-09. **`0.2.0`** (the `AddZbSerilog` minimum-level governance hook, scadaproj#12) is built here but -**not published**. Adoption history is in the component backlog: +**`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 +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: - `~/Desktop/scadaproj/components/observability/GAPS.md` diff --git a/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry.Serilog/ZbSerilogConfig.cs b/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry.Serilog/ZbSerilogConfig.cs index 39cb6c6..0f98c2f 100644 --- a/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry.Serilog/ZbSerilogConfig.cs +++ b/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry.Serilog/ZbSerilogConfig.cs @@ -49,7 +49,20 @@ internal static class ZbSerilogConfig public static LoggerConfiguration Apply( LoggerConfiguration loggerConfiguration, ZbTelemetryOptions options, - IServiceProvider? serviceProvider) + IServiceProvider? serviceProvider) => + Apply(loggerConfiguration, options, serviceProvider, registeredTelemetry: null); + + /// + /// Full overload: is the options an AddZbTelemetry + /// call registered in the same container (or ). The OTLP log sink follows + /// it when does not select OTLP itself — see + /// . Identity enrichers always come from . + /// + public static LoggerConfiguration Apply( + LoggerConfiguration loggerConfiguration, + ZbTelemetryOptions options, + IServiceProvider? serviceProvider, + ZbTelemetryOptions? registeredTelemetry) { ArgumentNullException.ThrowIfNull(loggerConfiguration); ArgumentNullException.ThrowIfNull(options); @@ -75,7 +88,10 @@ internal static class ZbSerilogConfig ApplyRedaction(loggerConfiguration, serviceProvider); } - ApplyOpenTelemetryExport(loggerConfiguration, options); + if (ResolveLogExport(options, registeredTelemetry) is { } export) + { + ApplyOpenTelemetryExport(loggerConfiguration, export); + } return loggerConfiguration; } @@ -90,6 +106,33 @@ internal static class ZbSerilogConfig internal static void ApplyRedaction(LoggerConfiguration loggerConfiguration, IServiceProvider serviceProvider) => loggerConfiguration.Enrich.With(new RedactionEnricher(serviceProvider)); + /// + /// Chooses the options the OTLP log sink is built from, or for no sink: + /// + /// when it selects itself + /// (the pre-0.3.0 behaviour; an app that builds its logger outside the host container, such as + /// ScadaBridge, passes the exporter here); + /// else the AddZbTelemetry registration in the same container when it selects + /// OTLP — so <App>:Telemetry:Exporter=Otlp switches logs along with metrics and + /// traces, with the identical Resource (scadaproj#55); + /// else none. + /// + /// Whichever is chosen, its = + /// keeps logs local. + /// + internal static ZbTelemetryOptions? ResolveLogExport( + ZbTelemetryOptions serilogOptions, + ZbTelemetryOptions? registeredTelemetry) + { + ArgumentNullException.ThrowIfNull(serilogOptions); + + var source = serilogOptions.Exporter == ZbExporter.Otlp + ? serilogOptions + : registeredTelemetry is { Exporter: ZbExporter.Otlp } ? registeredTelemetry : null; + + return source is { ExportLogs: true } ? source : null; + } + /// /// Adds a WriteTo.OpenTelemetry log sink when an OTLP exporter is explicitly /// selected ( = ). diff --git a/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry.Serilog/ZbSerilogExtensions.cs b/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry.Serilog/ZbSerilogExtensions.cs index 9f5931e..aa02d31 100644 --- a/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry.Serilog/ZbSerilogExtensions.cs +++ b/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry.Serilog/ZbSerilogExtensions.cs @@ -1,3 +1,4 @@ +using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Hosting; using Serilog; using Serilog.Events; @@ -14,6 +15,14 @@ namespace ZB.MOM.WW.Telemetry.Serilog; /// AddZbTelemetry in the core package for that. /// /// +/// OTLP logs (0.3.0+). An OTLP log sink is added when the options passed here select +/// Exporter = Otlp, or otherwise when an AddZbTelemetry call in the same service +/// collection does — the sink then uses that registration's endpoint and Resource, so logs go where +/// metrics and traces go. ZbTelemetryOptions.ExportLogs = false on the chosen options keeps +/// logs local. Levels and the configuration-driven sinks are unaffected. +/// +/// +/// /// This method intentionally does not set the process-global /// (via CreateBootstrapLogger or otherwise). Mutating /// process-global state in a shared library causes "logger is already frozen" exceptions @@ -119,7 +128,11 @@ public static class ZbSerilogExtensions // enrichers in registration order, so a RedactionEnricher registered before // ConfigureLogger would let hook-added enrichers stamp properties that reach every // sink unredacted. Apply() is told there is no provider so it skips redaction here. - ZbSerilogConfig.Apply(loggerConfiguration, options, serviceProvider: null); + // The OTLP log sink follows the AddZbTelemetry registration in this container when + // these options do not select OTLP themselves (scadaproj#55). Resolved here, inside + // the AddSerilog callback, so the AddZbTelemetry/AddZbSerilog call order is irrelevant. + var registered = serviceProvider.GetService()?.Options; + ZbSerilogConfig.Apply(loggerConfiguration, options, serviceProvider: null, registered); serilogOptions.ConfigureLogger?.Invoke(loggerConfiguration, serviceProvider); diff --git a/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry/ZB.MOM.WW.Telemetry.csproj b/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry/ZB.MOM.WW.Telemetry.csproj index 79aa63c..6752846 100644 --- a/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry/ZB.MOM.WW.Telemetry.csproj +++ b/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry/ZB.MOM.WW.Telemetry.csproj @@ -29,6 +29,9 @@ <_Parameter1>ZB.MOM.WW.Telemetry.Serilog.Tests + + <_Parameter1>ZB.MOM.WW.Telemetry.Tests + diff --git a/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry/ZbResource.cs b/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry/ZbResource.cs index 3c8b962..634fef3 100644 --- a/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry/ZbResource.cs +++ b/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry/ZbResource.cs @@ -1,4 +1,5 @@ using System.Collections.Generic; +using System.Reflection; using OpenTelemetry.Resources; namespace ZB.MOM.WW.Telemetry; @@ -19,12 +20,70 @@ public static class ZbResource public static string InstanceId => $"{System.Environment.MachineName}:{System.Environment.ProcessId}"; + /// + /// Resource keys owned by first-class members (or computed by + /// the library). may not set them. + /// + public static IReadOnlySet ReservedAttributeKeys { get; } = new HashSet(StringComparer.Ordinal) + { + "service.name", + "service.namespace", + "service.version", + "service.instance.id", + "host.name", + "site.id", + "node.role", + }; + + private static readonly Lazy EntryAssemblyVersion = + new(() => VersionOf(Assembly.GetEntryAssembly())); + + /// + /// The service.version used when is + /// : the entry assembly's AssemblyInformationalVersion (the family + /// apps stamp the git SHA there), else its assembly version, else + /// (attribute omitted). Computed once per process. + /// + public static string? DefaultServiceVersion => EntryAssemblyVersion.Value; + + /// + /// Version string of : its AssemblyInformationalVersion when + /// present and non-blank, else its assembly version, else . + /// + /// The assembly to read, typically the entry assembly. + internal static string? VersionOf(Assembly? assembly) + { + if (assembly is null) + { + return null; + } + + var informational = assembly.GetCustomAttribute()?.InformationalVersion; + if (!string.IsNullOrWhiteSpace(informational)) + { + return informational; + } + + return assembly.GetName().Version?.ToString(); + } + + /// + /// The effective service.version for : the explicit value when + /// set ("" means omit, returned as ), else + /// . + /// + internal static string? ResolveServiceVersion(ZbTelemetryOptions options, string? defaultVersion) => + options.ServiceVersion is null + ? defaultVersion + : options.ServiceVersion.Length == 0 ? null : options.ServiceVersion; + /// /// Returns a pre-populated with service.name, /// service.namespace, service.version, service.instance.id, - /// site.id, node.role, and host.name (always - /// ). Attributes with null values are omitted - /// from the Resource. + /// site.id, node.role, host.name (always + /// ) and every + /// entry. Optional attributes with null + /// values are omitted; a null ServiceVersion defaults to . /// /// The telemetry options describing the service identity. public static ResourceBuilder Build(ZbTelemetryOptions options) => @@ -36,26 +95,44 @@ public static class ZbResource /// Serilog OTLP log sink — derives its attributes from this one map, so logs can never drift /// from metrics/traces. Required attributes (service.name, service.namespace, /// service.instance.id, host.name) are always present; optional ones - /// (service.version, site.id, node.role) are included only when the - /// corresponding option is non-null/non-empty, matching the Resource's omission rules. + /// (site.id, node.role) are included only when the corresponding option is + /// non-null/non-empty; service.version follows + /// (null = , "" = omitted); every + /// entry is included. /// /// The telemetry options describing the service identity. /// The canonical attribute map carried by all three signals. - public static IReadOnlyDictionary BuildAttributes(ZbTelemetryOptions options) + public static IReadOnlyDictionary BuildAttributes(ZbTelemetryOptions options) => + BuildAttributes(options, DefaultServiceVersion); + + /// + /// with an explicit automatic + /// service.version (the test seam for the entry-assembly default). + /// + internal static IReadOnlyDictionary BuildAttributes(ZbTelemetryOptions options, string? defaultVersion) { ArgumentNullException.ThrowIfNull(options); - var attributes = new Dictionary(StringComparer.Ordinal) - { - ["service.name"] = options.ServiceName, - ["service.namespace"] = options.ServiceNamespace, - ["service.instance.id"] = InstanceId, - ["host.name"] = System.Environment.MachineName, - }; + var attributes = new Dictionary(StringComparer.Ordinal); - if (!string.IsNullOrEmpty(options.ServiceVersion)) + // Caller-supplied extras first; the first-class keys below are reserved (the validator + // rejects them in ResourceAttributes), so nothing here can be shadowed. + if (options.ResourceAttributes is { } extras) { - attributes["service.version"] = options.ServiceVersion; + foreach (var (key, value) in extras) + { + attributes[key] = value; + } + } + + attributes["service.name"] = options.ServiceName; + attributes["service.namespace"] = options.ServiceNamespace; + attributes["service.instance.id"] = InstanceId; + attributes["host.name"] = System.Environment.MachineName; + + if (ResolveServiceVersion(options, defaultVersion) is { } version) + { + attributes["service.version"] = version; } if (!string.IsNullOrEmpty(options.SiteId)) diff --git a/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry/ZbTelemetryExtensions.cs b/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry/ZbTelemetryExtensions.cs index 5854cb0..997d241 100644 --- a/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry/ZbTelemetryExtensions.cs +++ b/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry/ZbTelemetryExtensions.cs @@ -48,6 +48,11 @@ public static class ZbTelemetryExtensions // same fail-fast treatment (Telemetry-011). ValidateRequired(options, nameof(options)); + // Published for the Serilog companion: AddZbSerilog's OTLP log sink follows this + // registration's exporter/endpoint/identity so that logs go where metrics and traces go + // without the app repeating the settings (scadaproj#55). + services.AddSingleton(new ZbTelemetryRegistration(options)); + services.AddOpenTelemetry() .ConfigureResource(rb => ZbResource.Configure(rb, options)) .WithMetrics(metrics => diff --git a/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry/ZbTelemetryOptions.cs b/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry/ZbTelemetryOptions.cs index f52b1b3..92e40de 100644 --- a/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry/ZbTelemetryOptions.cs +++ b/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry/ZbTelemetryOptions.cs @@ -35,8 +35,11 @@ public sealed class ZbTelemetryOptions public string ServiceNamespace { get; set; } = "ZB.MOM.WW"; /// - /// Optional. Populate from AssemblyInformationalVersion. - /// Populates OTel Resource service.version. + /// Populates OTel Resource service.version. (the default) means + /// automatic: the entry assembly's AssemblyInformationalVersion (every family app + /// stamps the git SHA there, e.g. 1.0.0+424db155…), falling back to its assembly version + /// (see ). Set a value to override it; set + /// "" to omit the attribute. Before 0.3.0 omitted it. /// public string? ServiceVersion { get; set; } @@ -52,6 +55,17 @@ public sealed class ZbTelemetryOptions /// public string? NodeRole { get; set; } + /// + /// Extra OTel Resource attributes carried by every signal (metrics, traces and the Serilog OTLP + /// log sink), e.g. ["otopcua.cluster.id"] = "c1". Values must be non-null; use strings, + /// booleans, integers or doubles. Keys owned by a first-class option — service.name, + /// service.namespace, service.version, service.instance.id, + /// host.name, site.id, node.role — are rejected at startup; set the option + /// instead (). + /// + public IDictionary ResourceAttributes { get; set; } = + new Dictionary(StringComparer.Ordinal); + /// /// App-specific Meter names to register with the OTel MeterProvider. Standard instrumentation /// meters are added automatically (ASP.NET Core, HttpClient, runtime, process). @@ -73,4 +87,13 @@ public sealed class ZbTelemetryOptions /// OTLP gRPC endpoint, e.g. "http://collector:4317". /// public string? OtlpEndpoint { get; set; } + + /// + /// When = , also export logs to the same + /// through the ZB.MOM.WW.Telemetry.Serilog OTLP log sink. + /// Default . Set to keep logs on the local sinks + /// only while metrics and traces go to OTLP. Ignored for the Prometheus exporter, and ignored + /// when the Serilog companion package is not used. + /// + public bool ExportLogs { get; set; } = true; } diff --git a/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry/ZbTelemetryOptionsValidator.cs b/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry/ZbTelemetryOptionsValidator.cs index ee0fc15..7eb8bce 100644 --- a/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry/ZbTelemetryOptionsValidator.cs +++ b/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry/ZbTelemetryOptionsValidator.cs @@ -20,6 +20,8 @@ internal static class ZbTelemetryOptionsValidator { ArgumentNullException.ThrowIfNull(options); + ValidateResourceAttributes(options, paramName); + if (options.Exporter != ZbExporter.Otlp) { return; @@ -46,4 +48,36 @@ internal static class ZbTelemetryOptionsValidator paramName); } } + + private static void ValidateResourceAttributes(ZbTelemetryOptions options, string paramName) + { + if (options.ResourceAttributes is not { Count: > 0 } extras) + { + return; + } + + foreach (var (key, value) in extras) + { + if (string.IsNullOrWhiteSpace(key)) + { + throw new ArgumentException( + "ZbTelemetryOptions.ResourceAttributes contains a blank key.", paramName); + } + + if (ZbResource.ReservedAttributeKeys.Contains(key)) + { + throw new ArgumentException( + $"ZbTelemetryOptions.ResourceAttributes may not set '{key}'; it is owned by a " + + "first-class option (ServiceName, ServiceNamespace, ServiceVersion, SiteId, NodeRole) " + + "or computed by the library.", + paramName); + } + + if (value is null) + { + throw new ArgumentException( + $"ZbTelemetryOptions.ResourceAttributes['{key}'] is null.", paramName); + } + } + } } diff --git a/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry/ZbTelemetryRegistration.cs b/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry/ZbTelemetryRegistration.cs new file mode 100644 index 0000000..7204560 --- /dev/null +++ b/ZB.MOM.WW.Telemetry/src/ZB.MOM.WW.Telemetry/ZbTelemetryRegistration.cs @@ -0,0 +1,9 @@ +namespace ZB.MOM.WW.Telemetry; + +/// +/// The options an AddZbTelemetry call registered, published in DI so the Serilog companion +/// (AddZbSerilog) can send logs to the same OTLP endpoint with the same Resource as metrics +/// and traces. Internal: the companion assembly sees it through InternalsVisibleTo. +/// +/// The validated options passed to AddZbTelemetry. +internal sealed record ZbTelemetryRegistration(ZbTelemetryOptions Options); diff --git a/ZB.MOM.WW.Telemetry/tests/ZB.MOM.WW.Telemetry.Serilog.Tests/OtlpLogExportTests.cs b/ZB.MOM.WW.Telemetry/tests/ZB.MOM.WW.Telemetry.Serilog.Tests/OtlpLogExportTests.cs new file mode 100644 index 0000000..c7770d8 --- /dev/null +++ b/ZB.MOM.WW.Telemetry/tests/ZB.MOM.WW.Telemetry.Serilog.Tests/OtlpLogExportTests.cs @@ -0,0 +1,199 @@ +using System.Collections.Concurrent; +using System.Text; +using Microsoft.AspNetCore.Builder; +using Microsoft.AspNetCore.Hosting; +using Microsoft.AspNetCore.Http; +using Microsoft.AspNetCore.Server.Kestrel.Core; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using Microsoft.Extensions.Logging; +using Serilog; +using ZB.MOM.WW.Telemetry; +using ZB.MOM.WW.Telemetry.Serilog; + +namespace ZB.MOM.WW.Telemetry.Serilog.Tests; + +/// +/// scadaproj#55: logs follow AddZbTelemetry's OTLP exporter. Before 0.3.0 the sink keyed only +/// on the options passed to AddZbSerilog, which every app filled with the service name alone, +/// so no app ever exported a log record. +/// +public sealed class OtlpLogExportTests +{ + private const string LogsPath = "/opentelemetry.proto.collector.logs.v1.LogsService/Export"; + private const string MetricsPath = "/opentelemetry.proto.collector.metrics.v1.MetricsService/Export"; + + // --- the decision --------------------------------------------------------------------- + + private static ZbTelemetryOptions Otlp(string name, bool exportLogs = true) => new() + { + ServiceName = name, + Exporter = ZbExporter.Otlp, + OtlpEndpoint = "http://collector:4317", + ExportLogs = exportLogs, + }; + + [Fact] + public void Serilog_options_selecting_Otlp_win() + { + var own = Otlp("own"); + Assert.Same(own, ZbSerilogConfig.ResolveLogExport(own, Otlp("registered"))); + } + + [Fact] + public void Registered_telemetry_options_are_followed_when_Serilog_options_do_not_select_Otlp() + { + var registered = Otlp("registered"); + Assert.Same(registered, ZbSerilogConfig.ResolveLogExport(new ZbTelemetryOptions { ServiceName = "own" }, registered)); + } + + [Fact] + public void No_sink_when_nothing_selects_Otlp() + { + Assert.Null(ZbSerilogConfig.ResolveLogExport(new ZbTelemetryOptions { ServiceName = "own" }, null)); + Assert.Null(ZbSerilogConfig.ResolveLogExport( + new ZbTelemetryOptions { ServiceName = "own" }, + new ZbTelemetryOptions { ServiceName = "registered", OtlpEndpoint = "http://collector:4317" })); + } + + [Fact] + public void ExportLogs_false_keeps_logs_local_on_either_path() + { + Assert.Null(ZbSerilogConfig.ResolveLogExport(new ZbTelemetryOptions { ServiceName = "own" }, Otlp("registered", exportLogs: false))); + Assert.Null(ZbSerilogConfig.ResolveLogExport(Otlp("own", exportLogs: false), null)); + } + + // --- end to end against a loopback OTLP gRPC receiver ----------------------------------- + + /// Minimal OTLP/gRPC receiver: records each export call's path and body, answers OK. + private sealed class FakeOtlpReceiver : IAsyncDisposable + { + private readonly WebApplication _app; + + public ConcurrentBag<(string Path, byte[] Body)> Calls { get; } = new(); + + public string Endpoint { get; } + + private FakeOtlpReceiver(WebApplication app, string endpoint) + { + _app = app; + Endpoint = endpoint; + } + + public static async Task StartAsync() + { + var builder = WebApplication.CreateSlimBuilder(); + builder.Logging.ClearProviders(); + builder.WebHost.ConfigureKestrel(k => k.Listen(System.Net.IPAddress.Loopback, 0, + l => l.Protocols = HttpProtocols.Http2)); + var app = builder.Build(); + FakeOtlpReceiver? receiver = null; + app.Run(async context => + { + using var buffer = new MemoryStream(); + await context.Request.Body.CopyToAsync(buffer); + receiver!.Calls.Add((context.Request.Path.Value ?? "", buffer.ToArray())); + context.Response.ContentType = "application/grpc"; + context.Response.AppendTrailer("grpc-status", "0"); + // One empty, uncompressed gRPC message (the Export*ServiceResponse). + await context.Response.Body.WriteAsync(new byte[5]); + }); + await app.StartAsync(); + var address = app.Urls.Single().Replace("[::1]", "127.0.0.1"); + receiver = new FakeOtlpReceiver(app, address); + return receiver; + } + + public bool Received(string path) => Calls.Any(c => c.Path == path); + + public string BodiesOf(string path) => + string.Join("\n", Calls.Where(c => c.Path == path).Select(c => Encoding.UTF8.GetString(c.Body))); + + public async ValueTask DisposeAsync() + { + await _app.StopAsync(); + await _app.DisposeAsync(); + } + } + + /// + /// The app shape every family app uses: AddZbSerilog with the service name only, and the + /// exporter set on AddZbTelemetry. Disposing the host flushes the log batch and the + /// final metric export. + /// + private static async Task RunAppAsync(FakeOtlpReceiver receiver, ZbExporter exporter, bool exportLogs) + { + var builder = Host.CreateApplicationBuilder(); + builder.AddZbSerilog(o => o.ServiceName = "log-export-test"); + builder.Services.AddZbTelemetry(o => + { + o.ServiceName = "log-export-test"; + o.ServiceVersion = "9.8.7+e2e"; + o.SiteId = "site-e2e"; + o.NodeRole = "role-e2e"; + o.ResourceAttributes["zb.test.marker"] = "marker-e2e"; + o.Exporter = exporter; + o.OtlpEndpoint = receiver.Endpoint; + o.ExportLogs = exportLogs; + }); + + using (var host = builder.Build()) + { + // Resolve the meter provider so a metrics export can serve as the positive control. + _ = host.Services.GetService(); + host.Services.GetRequiredService().Information("hello over otlp {Marker}", "log-line-e2e"); + } + + // The sink's batch and the metric reader flush on dispose; allow the h2c round-trips to land. + for (var i = 0; i < 50 && !receiver.Received(exporter == ZbExporter.Otlp ? MetricsPath : LogsPath); i++) + { + await Task.Delay(100); + } + } + + [Fact] + public async Task Logs_follow_AddZbTelemetry_Otlp_with_the_same_Resource() + { + await using var receiver = await FakeOtlpReceiver.StartAsync(); + + await RunAppAsync(receiver, ZbExporter.Otlp, exportLogs: true); + for (var i = 0; i < 50 && !receiver.Received(LogsPath); i++) + { + await Task.Delay(100); + } + + Assert.True(receiver.Received(LogsPath), "no OTLP logs export call arrived; paths: " + + string.Join(", ", receiver.Calls.Select(c => c.Path).Distinct())); + var body = receiver.BodiesOf(LogsPath); + Assert.Contains("log-line-e2e", body); + Assert.Contains("log-export-test", body); + Assert.Contains("9.8.7+e2e", body); + Assert.Contains("site-e2e", body); + Assert.Contains("role-e2e", body); + Assert.Contains("marker-e2e", body); + } + + [Fact] + public async Task ExportLogs_false_sends_metrics_but_no_logs() + { + await using var receiver = await FakeOtlpReceiver.StartAsync(); + + await RunAppAsync(receiver, ZbExporter.Otlp, exportLogs: false); + await Task.Delay(500); + + // Positive control: the same receiver, reachable, got the metrics export. + Assert.True(receiver.Received(MetricsPath), "positive control failed: no metrics export arrived"); + Assert.False(receiver.Received(LogsPath)); + } + + [Fact] + public async Task Prometheus_exporter_sends_no_logs() + { + await using var receiver = await FakeOtlpReceiver.StartAsync(); + + await RunAppAsync(receiver, ZbExporter.Prometheus, exportLogs: true); + await Task.Delay(500); + + Assert.Empty(receiver.Calls); + } +} diff --git a/ZB.MOM.WW.Telemetry/tests/ZB.MOM.WW.Telemetry.Serilog.Tests/ZB.MOM.WW.Telemetry.Serilog.Tests.csproj b/ZB.MOM.WW.Telemetry/tests/ZB.MOM.WW.Telemetry.Serilog.Tests/ZB.MOM.WW.Telemetry.Serilog.Tests.csproj index 67dba2a..5b778c7 100644 --- a/ZB.MOM.WW.Telemetry/tests/ZB.MOM.WW.Telemetry.Serilog.Tests/ZB.MOM.WW.Telemetry.Serilog.Tests.csproj +++ b/ZB.MOM.WW.Telemetry/tests/ZB.MOM.WW.Telemetry.Serilog.Tests/ZB.MOM.WW.Telemetry.Serilog.Tests.csproj @@ -16,6 +16,11 @@ + + + + + diff --git a/ZB.MOM.WW.Telemetry/tests/ZB.MOM.WW.Telemetry.Tests/ResourceIdentityTests.cs b/ZB.MOM.WW.Telemetry/tests/ZB.MOM.WW.Telemetry.Tests/ResourceIdentityTests.cs new file mode 100644 index 0000000..c8cfd4a --- /dev/null +++ b/ZB.MOM.WW.Telemetry/tests/ZB.MOM.WW.Telemetry.Tests/ResourceIdentityTests.cs @@ -0,0 +1,179 @@ +using System.Reflection; +using Microsoft.AspNetCore.Builder; +using Microsoft.Extensions.DependencyInjection; +using OpenTelemetry; +using OpenTelemetry.Metrics; +using OpenTelemetry.Trace; +using ZB.MOM.WW.Telemetry; + +namespace ZB.MOM.WW.Telemetry.Tests; + +/// +/// scadaproj#55: service.version defaults from the entry assembly, and caller-supplied +/// Resource attributes reach the Resource the SDK pipeline actually uses. +/// +public sealed class ResourceIdentityTests +{ + private static Dictionary PipelineResource(Action configure) + { + var builder = WebApplication.CreateBuilder(); + builder.AddZbTelemetry(configure); + using var app = builder.Build(); + var tracer = app.Services.GetRequiredService(); + var meter = app.Services.GetRequiredService(); + var traceAttrs = tracer.GetResource().Attributes.ToDictionary(a => a.Key, a => a.Value); + var meterAttrs = meter.GetResource().Attributes.ToDictionary(a => a.Key, a => a.Value); + // Metrics and traces carry the identical Resource. + Assert.Equal(traceAttrs.OrderBy(a => a.Key), meterAttrs.OrderBy(a => a.Key)); + return traceAttrs; + } + + [Fact] + public void VersionOf_reads_the_informational_version() + { + var assembly = typeof(ZbResource).Assembly; + var expected = assembly.GetCustomAttribute()!.InformationalVersion; + + Assert.Equal(expected, ZbResource.VersionOf(assembly)); + Assert.StartsWith("0.3.0", ZbResource.VersionOf(assembly)); + Assert.Null(ZbResource.VersionOf(null)); + } + + [Fact] + public void DefaultServiceVersion_is_the_entry_assembly_version() + { + Assert.NotNull(Assembly.GetEntryAssembly()); + Assert.Equal(ZbResource.VersionOf(Assembly.GetEntryAssembly()), ZbResource.DefaultServiceVersion); + Assert.False(string.IsNullOrEmpty(ZbResource.DefaultServiceVersion)); + } + + [Fact] + public void Null_ServiceVersion_takes_the_default() + { + var attributes = ZbResource.BuildAttributes(new ZbTelemetryOptions { ServiceName = "x" }, "1.0.0+abc123"); + + Assert.Equal("1.0.0+abc123", attributes["service.version"]); + } + + [Fact] + public void Explicit_ServiceVersion_overrides_the_default() + { + var attributes = ZbResource.BuildAttributes( + new ZbTelemetryOptions { ServiceName = "x", ServiceVersion = "2.0.0" }, "1.0.0+abc123"); + + Assert.Equal("2.0.0", attributes["service.version"]); + } + + [Fact] + public void Empty_ServiceVersion_omits_the_attribute_even_with_a_default() + { + var attributes = ZbResource.BuildAttributes( + new ZbTelemetryOptions { ServiceName = "x", ServiceVersion = "" }, "1.0.0+abc123"); + + Assert.False(attributes.ContainsKey("service.version")); + } + + [Fact] + public void No_default_and_null_ServiceVersion_omits_the_attribute() + { + var attributes = ZbResource.BuildAttributes(new ZbTelemetryOptions { ServiceName = "x" }, defaultVersion: null); + + Assert.False(attributes.ContainsKey("service.version")); + } + + [Fact] + public void Pipeline_Resource_carries_the_default_service_version() + { + var attributes = PipelineResource(o => o.ServiceName = "telemetry-test"); + + Assert.Equal(ZbResource.DefaultServiceVersion, attributes["service.version"]); + } + + [Fact] + public void Pipeline_Resource_carries_identity_and_extra_attributes() + { + var attributes = PipelineResource(o => + { + o.ServiceName = "telemetry-test"; + o.ServiceVersion = "7.7.7"; + o.SiteId = "site-a"; + o.NodeRole = "driver"; + o.ResourceAttributes["otopcua.cluster.id"] = "c1"; + o.ResourceAttributes["zb.node.ordinal"] = 2L; + }); + + Assert.Equal("7.7.7", attributes["service.version"]); + Assert.Equal("site-a", attributes["site.id"]); + Assert.Equal("driver", attributes["node.role"]); + Assert.Equal("c1", attributes["otopcua.cluster.id"]); + Assert.Equal(2L, attributes["zb.node.ordinal"]); + } + + [Fact] + public void Extra_attributes_are_in_BuildAttributes() + { + var options = new ZbTelemetryOptions { ServiceName = "x" }; + options.ResourceAttributes["deployment.environment.name"] = "dev"; + + Assert.Equal("dev", ZbResource.BuildAttributes(options)["deployment.environment.name"]); + } + + [Theory] + [InlineData("service.name")] + [InlineData("service.namespace")] + [InlineData("service.version")] + [InlineData("service.instance.id")] + [InlineData("host.name")] + [InlineData("site.id")] + [InlineData("node.role")] + public void Reserved_keys_in_ResourceAttributes_are_rejected(string key) + { + var builder = WebApplication.CreateBuilder(); + var ex = Assert.Throws(() => builder.AddZbTelemetry(o => + { + o.ServiceName = "telemetry-test"; + o.ResourceAttributes[key] = "spoof"; + })); + + Assert.Equal("configure", ex.ParamName); + Assert.Contains(key, ex.Message); + } + + [Fact] + public void Null_value_in_ResourceAttributes_is_rejected_on_the_prebuilt_overload_too() + { + var options = new ZbTelemetryOptions { ServiceName = "telemetry-test" }; + options.ResourceAttributes["custom"] = null!; + + var ex = Assert.Throws(() => new ServiceCollection().AddZbTelemetry(options)); + Assert.Contains("custom", ex.Message); + } + + [Fact] + public void Blank_key_in_ResourceAttributes_is_rejected() + { + var builder = WebApplication.CreateBuilder(); + Assert.Throws(() => builder.AddZbTelemetry(o => + { + o.ServiceName = "telemetry-test"; + o.ResourceAttributes[" "] = "v"; + })); + } + + [Fact] + public void AddZbTelemetry_publishes_its_options_for_the_Serilog_companion() + { + var services = new ServiceCollection(); + services.AddZbTelemetry(o => + { + o.ServiceName = "telemetry-test"; + o.Exporter = ZbExporter.Otlp; + o.OtlpEndpoint = "http://collector:4317"; + }); + + using var provider = services.BuildServiceProvider(); + var registration = provider.GetRequiredService(); + Assert.Equal("telemetry-test", registration.Options.ServiceName); + Assert.Equal("http://collector:4317", registration.Options.OtlpEndpoint); + } +} diff --git a/ZB.MOM.WW.Telemetry/tests/ZB.MOM.WW.Telemetry.Tests/ZbResourceTests.cs b/ZB.MOM.WW.Telemetry/tests/ZB.MOM.WW.Telemetry.Tests/ZbResourceTests.cs index bb3b2ae..1788e66 100644 --- a/ZB.MOM.WW.Telemetry/tests/ZB.MOM.WW.Telemetry.Tests/ZbResourceTests.cs +++ b/ZB.MOM.WW.Telemetry/tests/ZB.MOM.WW.Telemetry.Tests/ZbResourceTests.cs @@ -36,7 +36,9 @@ public sealed class ZbResourceTests var options = new ZbTelemetryOptions { ServiceName = "mxgateway", - // ServiceVersion / SiteId / NodeRole left null + // "" = omit service.version (null now means the entry-assembly default, scadaproj#55); + // SiteId / NodeRole left null. + ServiceVersion = "", }; var resource = ZbResource.Build(options).Build();