Logging & tracing
Use one structured pipeline, exported over OTLP. Treat logs and traces as one telemetry stream.
Conflict of interest: The Serilog guidance cites Nicholas Blumhardt, who wrote Serilog and SerilogTracing and sells Seq through Datalust. The recommendations name the open-source libraries and the BCL
ActivityAPIs, not a product, and the fallback example deliberately targets an OTLP endpoint, not Seq.
Opinions
-
Log through
ILogger<T>, and declare every event as a source-generated[LoggerMessage]partial method.logger.LogInformation($"...")boxes, allocates, and formats the string even when the level is off. The generator skips that work, and keeps the message template, so structured sinks get named properties. UnlikeLoggerMessage.Define, it has no six-parameter limit, allows a dynamic level, and reports duplicate event IDs at compile time. (Microsoft Learn: Compile-time logging source generation)public partial class OrderService(ILogger<OrderService> logger) { [LoggerMessage(EventId = 100, Level = LogLevel.Information, Message = "Order {OrderId} accepted for {CustomerId}")] public partial void OrderAccepted(Guid orderId, string customerId); }Never interpolate a string in a log call.
LogInformation($"Order {orderId} accepted")also loses the structure: the sink gets one string, with noOrderIdproperty. -
Create spans with
ActivitySource.StartActivity, not log lines that record durations.Activityis the BCL span type, and ASP.NET Core andSystem.Net.Httpalready create it and propagate W3Ctraceparentcontext. A span records its timing and its parent, which a logged stopwatch reading can't. (Microsoft Learn: Distributed tracing concepts) For work that crosses a process or time boundary, propagate the context explicitly, as aspnet-core.md describes. -
Control tracing cost by sampling when the activity is created, not with a sink filter. Sampling runs in the
ActivityListener.Samplecallback. The listener can decline the activity, create an ID-only activity that still propagates context, or record it fully. Dropping spans at the exporter instead pays for creating and recording each one first. With the OpenTelemetry SDK, set its sampler, not a listener of your own: for more than capturing every trace, the expectation is that you "plug in the OpenTelemetry SDK and use its sampling APIs". Write the callback yourself only when you listen without the SDK, as Blumhardt's Serilog bridge does.Sampleis used only for W3C trace context. A listener that also has to sample legacy hierarchical IDs setsSampleUsingParentId, which then takes over for both. (Microsoft Learn: Distributed tracing concepts, Blumhardt: .NET'sActivityListenersampling API) -
Export over OTLP to a collector, and keep vendor SDKs out of application code. The default pipeline is
Microsoft.Extensions.Loggingwith the OpenTelemetry exporter. With one wire format, the backend is a deployment choice, not a code dependency.- Serilog isn't the default because it adds a second configuration surface beside
ILogger's. If you need one of its sinks,SerilogTracingsendsActivityspans through the same pipeline as the logs. (Blumhardt: SerilogTracing)
- Serilog isn't the default because it adds a second configuration surface beside
-
Give the log pipeline a durable local fallback, and expect it to lag. A network collector goes down eventually, and an outage is when you need the logs most. Chain a rolling file behind the network sink. Network sinks retry with backoff before they report failure, so the file usually starts receiving events about ten minutes into an outage. To change that, set
BatchingOptions.RetryTimeLimit. (Blumhardt: Serilog fallback sinks, Blumhardt: Visualizing the Serilog 4.1 batch retry algorithm)Log.Logger = new LoggerConfiguration() .WriteTo.FallbackChain( wt => wt.OpenTelemetry(endpoint: "https://otlp.example/v1/logs"), wt => wt.File( "logs/app-.txt", rollingInterval: RollingInterval.Day, formatProvider: CultureInfo.InvariantCulture)) .CreateLogger();With the default pipeline, run a collector on localhost, and let it own the durable queue.
AddOtlpExporterdoesn't retry a failed export by default. Its in-memory and disk retry are experimental, behind theOTEL_DOTNET_EXPERIMENTAL_OTLP_RETRYenvironment variable, so a failed export or a killed process loses what was in flight. An export to the loopback address succeeds while the backend is down. Configure retry and disk buffering in the collector, not the app. The collector's defaults lose data too: its retry gives up aftermax_elapsed_time, 300 seconds by default, and when the sending queue is full, data "is typically dropped". Setsending_queue.storagefor a persistent queue, and sizequeue_sizeandmax_elapsed_timefor the outage you plan to ride out. Alert on theotelcol_exporter_enqueue_failed_*metrics, which report data the queue rejected. (OpenTelemetry Collector: Exporter helper, OpenTelemetry .NET: OTLP exporter, Microsoft Learn: .NET observability with OpenTelemetry)If you can't run a local collector, use Serilog with the chain above. Skip both only when the logs are for diagnostics, not an audit trail, and record that decision.
Levels
- Use
Informationfor events an operator wants in production, andDebugfor developers. Set the default minimum level toInformation. Raise noisy framework categories, such asMicrosoft.AspNetCore, toWarningin configuration instead of deleting the calls. (Microsoft Learn: Logging in .NET and ASP.NET Core) - Pass an exception as the
exceptionargument, never in the message. The generator treats the firstExceptionparameter specially, and structured sinks record its type, message, and stack trace as separate fields. (Microsoft Learn: Compile-time logging source generation) -
Redact classified data in the pipeline, not at the call site.
Microsoft.Extensions.Compliance.Redactionpicks redactors by data classification. It takes two calls:AddRedactionon the service collection, to "Register and configure redactors for each classification in your DI container", andEnableRedaction()on the logging builder, which also needs theMicrosoft.Extensions.Telemetrypackage. After both, a log method's parameter annotated with one of your classifications is redacted before it's written. Redaction covers only what you classify, so Learn's steps end with "Regularly audit your logs to ensure no sensitive data is exposed". It doesn't cover the exception: the firstExceptionparameter goes to the logger whole, and a classification on it changes nothing, so keep classified values out of exception messages. A?? "***"at the call site leaks the value as soon as someone logs it elsewhere. (Microsoft Learn: Compile-time logging source generation, Microsoft Learn: Data redaction in .NET)