Telemetry composed over the standard .NET APIs
Context
Logs and metrics written with different APIs drift apart: different names for the same operation, context in some places only, and every package choosing its own metrics client. Organizations also differ in logging providers, property names and metrics backends, and most already run one: the toolkit must feed it rather than ask for a replacement.
Decision
Toolkit code writes telemetry through Core.Telemetry, which is built on the standard .NET APIs and does not depend on Serilog or any vendor SDK:
ICoreTelemetryholds the two primitives: a MicrosoftILoggerand anIMetricRecorder. The default implementation takes the logger from the application’sILoggerFactory;IMetricRecorderis a small provider-neutral contract (counters, gauges, histograms, durations in seconds) whose default recordsSystem.Diagnostics.Metricsinstruments through the application’sIMeterFactory, so OpenTelemetry collects them and exports them with OTLP without custom code.AppTelemetryis a concrete class that receivesICoreTelemetryand holds the toolkit conventions on top: call-site attribution, standard metric names, timers, monitored actions, log helpers andLogContextscopes. Toolkit packages depend on it (or onICoreTelemetrywhen they need only the primitives), so every package emits through the same pipeline.- Registration is DI-first.
AddCoreTelemetry()usesTryAdd, so what the application registered is kept, and anything registered later wins. Applications replace the logging providers, the recorder,ICoreTelemetryorAppTelemetrythrough DI; aModuleTelemetryBasepackages that choice as a module. Instances the application supplies are never disposed by the toolkit. - Serilog is optional.
Infrastructure.Telemetry.Serilogregisters Serilog as one more logging provider and adds opt-in extras (console defaults for tools, enrichers, log-based metrics). Swapping providers changes only the composition root. - Notable events are structured logs, not a vendor API. A stable
EventIdand properties, plus a counter when the count matters. Routing them to Datadog Events or New Relic custom events is configuration of a provider or exporter; no vendor package ships. - Correlation IDs are provider-neutral. They travel in
ILoggerscopes andActivitytags, set by the middleware and by the entry points of workers and message consumers.
Consequences
- A call site produces logs and metrics with matching context and no naming effort.
- Company specifics live in one module (logging providers, an exporter, optionally a recorder), outside the toolkit.
- Any logging provider and any OpenTelemetry-compatible backend works without changes to instrumentation code.
- The toolkit owns the conventions (names, tags, call sites), not the pipeline; it never creates a private logger or meter that bypasses the application’s.
- Metrics follow the standard .NET model, so backend behavior (temporality, units, naming rules) depends on the exporter and the vendor.
Alternatives considered
ILoggerandSystem.Diagnostics.Metricsdirectly, with no facade. Standard, but without the call-site conventions and with the same boilerplate repeated in every package.- A Serilog-based facade in Core. Rejected: it forces one logging library on every adopter. Serilog remains available as an optional provider.
- A vendor SDK (Datadog, New Relic) inside the packages. Rejected by the Vendor-neutral value: OTLP and providers cover the vendors through configuration.