Skip to content

Logging & tracing

Targets net11.0 csharp-15Last reviewed 2026-11-14 freshSources ms-learn nicholas-blumhardt

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 Activity APIs, 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. Unlike LoggerMessage.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 no OrderId property.

  • Create spans with ActivitySource.StartActivity, not log lines that record durations. Activity is the BCL span type, and ASP.NET Core and System.Net.Http already create it and propagate W3C traceparent context. 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.Sample callback. 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. Sample is used only for W3C trace context. A listener that also has to sample legacy hierarchical IDs sets SampleUsingParentId, which then takes over for both. (Microsoft Learn: Distributed tracing concepts, Blumhardt: .NET's ActivityListener sampling API)

  • Export over OTLP to a collector, and keep vendor SDKs out of application code. The default pipeline is Microsoft.Extensions.Logging with 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, SerilogTracing sends Activity spans through the same pipeline as the logs. (Blumhardt: SerilogTracing)
  • 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. AddOtlpExporter doesn't retry a failed export by default. Its in-memory and disk retry are experimental, behind the OTEL_DOTNET_EXPERIMENTAL_OTLP_RETRY environment 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 after max_elapsed_time, 300 seconds by default, and when the sending queue is full, data "is typically dropped". Set sending_queue.storage for a persistent queue, and size queue_size and max_elapsed_time for the outage you plan to ride out. Alert on the otelcol_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 Information for events an operator wants in production, and Debug for developers. Set the default minimum level to Information. Raise noisy framework categories, such as Microsoft.AspNetCore, to Warning in configuration instead of deleting the calls. (Microsoft Learn: Logging in .NET and ASP.NET Core)
  • Pass an exception as the exception argument, never in the message. The generator treats the first Exception parameter 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.Redaction picks redactors by data classification. It takes two calls: AddRedaction on the service collection, to "Register and configure redactors for each classification in your DI container", and EnableRedaction() on the logging builder, which also needs the Microsoft.Extensions.Telemetry package. 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 first Exception parameter 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)