DcsvIo.D2.Telemetry 0.1.3-beta.1

DcsvIo.D2.Telemetry

OpenTelemetry SDK setup (traces / metrics / logs) + OTLP exporters (per-signal opt-in via canonical env vars) + IP-restricted Prometheus scraping endpoint + aggregation of every shared lib's ActivitySource and Meter into a single AddD2Telemetry() call. Foundation lib that composition-root hosts call to wire the OTel SDK without each service duplicating ~120 lines of OpenTelemetryBuilder / ConfigureResource / per-instrumentation registration boilerplate.

The lib is intentionally independent of DcsvIo.D2.Logging. The two libs cooperate at runtime via the MEL bridge — Serilog's writeToProviders: true (set by AddD2Logging) routes through the OTLP log exporter that AddD2Telemetry registers as an ILoggerProvider — without either lib referencing the other at compile time. Hosts may wire one without the other.

The lib does NOT own:

• Serilog configuration / sinks — DcsvIo.D2.Logging owns them.
• The [RedactData] enforcement pipeline — DcsvIo.D2.Logging owns it.
• [LoggerMessage] source-generated delegates — bootstrapping the OTel logs MEL provider during MEL bootstrap is circular.
• Self-monitoring counters for export failures — the OTel SDK's own internal diagnostics suffice for the foundation tier; consumers can wire EventListener against the SDK if lib-internal export-failure visibility is needed.

Install

dotnet add package DcsvIo.D2.Telemetry

Public API surface

Composition

services.AddD2Telemetry(configuration, opts =>
{
    opts.ServiceName = "edge";                       // optional — defaults from OTEL_SERVICE_NAME → IHostEnvironment.ApplicationName
    opts.OtlpTracesEndpoint = "https://otlp.example.com/v1/traces";  // optional — defaults from OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
    opts.AdditionalActivitySources = ["YourHost.Service"];    // optional — service-specific activity sources
});

// later, inside the endpoint-routing pipeline:
app.MapD2PrometheusEndpoint();

AddD2Telemetry(IConfiguration, Action<D2TelemetryOptions>?) registers the OpenTelemetry SDK builder, the OTLP exporters whose corresponding endpoint env vars are truthy, the in-process Prometheus exporter (when EnablePrometheusExporter is true), and the standard auto-instrumentations (AspNetCore, HttpClient, GrpcNetClient, Process, Runtime). Validates options at the first IOptions<D2TelemetryOptions>.Value resolution via ValidateOnStart() — fail-fast on invalid config.

MapD2PrometheusEndpoint() maps /metrics via OpenTelemetry's MapPrometheusScrapingEndpoint, attaches an endpoint filter that returns 403 Forbidden for requests whose connection-remote IP is neither loopback nor RFC 1918 private.

OTEL_SDK_DISABLED short-circuit

When the canonical OpenTelemetry env var OTEL_SDK_DISABLED is set to "true" (case-insensitive), BOTH AddD2Telemetry and MapD2PrometheusEndpoint short-circuit:

• AddD2Telemetry returns the unmutated services collection — no providers / exporters / instrumentations registered.
• MapD2PrometheusEndpoint returns the unmutated endpoints builder — no /metrics route mapped.

Consumers MUST NOT rely on MeterProvider / TracerProvider resolution from DI after AddD2Telemetry returns when the env var is set. Used in E2E tests where the OTel SDK is undesired (the SDK's per-process singleton state otherwise contaminates tests that build multiple hosts in sequence).

Configuration — D2TelemetryOptions

Constants

The OTEL_SERVICE_NAME_CONFIG_KEY value matches DcsvIo.D2.Logging's constant of the same name — both reference the OpenTelemetry-canonical env var so log + trace + metric service names stay aligned. Re-declared here rather than depending on DcsvIo.D2.Logging (the two libs are independent).

Telemetry surface coverage

AddD2Telemetry aggregates shared-lib ActivitySource / Meter wire names into the configured exporters. Package owners bind via published const string symbols (compile-time rename safety). Optional host auth modules may also emit under reserved OTel wire names registered as literals only (no ProjectReference into host packages from this lib).

Optional host auth meters: wire names "DcsvIo.D2.Auth" / "DcsvIo.D2.Auth.Outbound" are AssemblyName / OTel series labels for hosts that ship auth runtime modules. Public Telemetry registers those names as string literals so dashboards stay continuous; it does not ProjectReference host auth packages.

ActivitySource aggregation (4 sources — tracer provider)

Meter aggregation (6 meters — meter provider)

The two cache libs publish counters only — no spans — so they appear in the meter list but not the activity-source list. ProjectReferenced libs use source-of-truth const string symbols so a rename surfaces as a build break. Optional host auth names are literals. Spec-pinning unit tests in AggregatedTelemetrySourcesTests and D2TelemetryConstantsTests pin the literal wire values so an in-place value change surfaces as a test failure — operators querying Tempo / Prometheus by literal source name (DcsvIo.D2.Auth) are protected from silent wire-format drift.

Auto-instrumentations

Dependencies

Not referenced (wire literals only): optional host auth runtime + outbound modules. Public Telemetry registers OTel wire names "DcsvIo.D2.Auth" / "DcsvIo.D2.Auth.Outbound" as string literals — see AggregatedTelemetrySources.AUTH_WIRE_NAME / AUTH_OUTBOUND_WIRE_NAME.

Edge cases / gotchas

• OTel SDK builds singleton MeterProvider / TracerProvider per process. Tests that build multiple hosts in sequence see SDK static state contamination across host lifetimes. The lib's integration tests pin the contract via [Collection("OtelStaticState")] to serialize against any other test that touches the SDK.
• Infrastructure-path matching lives in DcsvIo.D2.AspNetCore. The AspNetCore-instrumentation Filter callback consumes the public InfrastructurePathMatcher; DcsvIo.D2.Logging's request-logging middleware consumes the same one. The path set (/health, /alive, /metrics, /.well-known) stays aligned across the two consumers without per-lib literal duplication.
• Cache libs (Redis, Local) expose only their Meter — no spans. The libs publish aggregate counters (hits, misses, sets, evictions) without per-call spans because cache work is sub-microsecond and per-call instrumentation would dominate it. The aggregation table reflects this — meter list includes both cache libs; activity-source list does not.
• MessagingTelemetry, RedisCacheTelemetry, and LocalCacheTelemetry are public static so their SOURCE_NAME consts are reachable cross-assembly. The consts themselves are public; the surrounding class visibility matches so cross-assembly references compile.
• Per-signal OTLP exporter is registered ONLY when its endpoint env var is truthy. When all three are absent, the SDK still builds — spans emit to in-process listeners; metrics flow to the Prometheus endpoint when enabled; logs flow through other MEL providers. This is the fail-soft behavior: production sets all three; dev / test omits any combination cleanly.
• HttpClient instrumentation's self-referential filter prevents infinite-loop instrumentation. Outbound calls whose URI starts with any configured OTLP endpoint are suppressed from span emission (else HttpClient → OTLP → HttpClient → OTLP loops forever).
• url.full query-string stripping is defense-in-depth. The OTel 1.15.x HttpClient instrumentation default already strips query strings from the standard span tags, but the EnrichWithHttpRequestMessage callback explicitly re-sets url.full to scheme + host + port + path so a future SDK regression doesn't silently leak query-string PII.
• OTLP collector unavailable → SDK retries internally + drops on full buffer. The OTel SDK's BatchExportProcessor owns retry / drop semantics; the lib does not add another layer. Operators notice unavailability via missing data in dashboards (the SDK's own internal diagnostics + EventListener against OpenTelemetry.EventSource provide drop-rate visibility for operators who wire it).