SerilogTracing 2.3.1-dev-00393

This is a prerelease version of SerilogTracing.
There is a newer version of this package available.
See the version list below for details.
dotnet add package SerilogTracing --version 2.3.1-dev-00393                
NuGet\Install-Package SerilogTracing -Version 2.3.1-dev-00393                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="SerilogTracing" Version="2.3.1-dev-00393" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add SerilogTracing --version 2.3.1-dev-00393                
#r "nuget: SerilogTracing, 2.3.1-dev-00393"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install SerilogTracing as a Cake Addin
#addin nuget:?package=SerilogTracing&version=2.3.1-dev-00393&prerelease

// Install SerilogTracing as a Cake Tool
#tool nuget:?package=SerilogTracing&version=2.3.1-dev-00393&prerelease                

SerilogTracing NuGet Version

SerilogTracing is a minimal tracing system that integrates Serilog with .NET's System.Diagnostics.Activity. You can use it to add distributed, hierarchical tracing to applications that use Serilog, and to consume traces generated by .NET components including HttpClient and ASP.NET Core.

Traces are written to standard Serilog sinks. Sinks with capable back-ends support full hierarchical tracing, and others will flatten traces into individual spans with timing information.

Here's the output of the included example application in the standard System.Console sink:

SerilogTracing terminal output

The same trace displayed in Seq:

SerilogTracing Seq output

And in Zipkin:

SerilogTracing Zipkin output

Getting started

This section walks through a very simple SerilogTracing example. To get started we'll create a simple .NET 8 console application and install some SerilogTracing packages.

mkdir example
cd example
dotnet new console
dotnet add package SerilogTracing
dotnet add package SerilogTracing.Expressions
dotnet add package Serilog.Sinks.Console

Replace the contents of the generated Program.cs with:

using Serilog;
using Serilog.Templates.Themes;
using SerilogTracing;
using SerilogTracing.Expressions;

Log.Logger = new LoggerConfiguration()
    .WriteTo.Console(Formatters.CreateConsoleTextFormatter(TemplateTheme.Code))
    .CreateLogger();

using var listener = new ActivityListenerConfiguration().TraceToSharedLogger();

using var activity = Log.Logger.StartActivity("Check {Host}", "example.com");
try
{
    var client = new HttpClient();
    var content = await client.GetStringAsync("https://example.com");
    Log.Information("Content length is {ContentLength}", content.Length);

    activity.Complete();
}
catch (Exception ex)
{
    activity.Complete(LogEventLevel.Fatal, ex);
}
finally
{
    await Log.CloseAndFlushAsync();
}

Running it will print some log events and spans to the console:

dotnet run

Let's break the example down a bit.

Setting up the logger

The Serilog pipeline is set up normally:

using Serilog;
using Serilog.Templates.Themes;
using SerilogTracing;
using SerilogTracing.Expressions;

Log.Logger = new LoggerConfiguration()
    .WriteTo.Console(Formatters.CreateConsoleTextFormatter(TemplateTheme.Code))
    .CreateLogger();

The Formatters.CreateConsoleTextFormatter() function comes from SerilogTracing.Expressions; you can ignore this and use a regular console output template, but the one we're using here produces nice output for spans that includes timing information. Dig into the implementation of the CreateConsoleTextFormatter() function if you'd like to see how to set up your own trace-specific formatting, it's pretty straightforward.

Enabling tracing with ActivityListenerConfiguration.TraceToSharedLogger()

This line sets up SerilogTracing's integration with .NET's diagnostic sources, and starts an activity listener in the background that will write spans from the framework and third-party libraries through your Serilog pipeline:

using var listener = new ActivityListenerConfiguration().TraceToSharedLogger();

This step is optional, but you'll need this if you want to view your SerilogTracing output as hierarchical, distributed traces: without it, HttpClient won't generate spans, and won't propagate trace ids along with outbound HTTP requests.

You can also configure SerilogTracing to send spans through a specific ILogger:

using Serilog;
using SerilogTracing;
using SerilogTracing.Expressions;

await using var logger = new LoggerConfiguration()
    .WriteTo.Console(Formatters.CreateConsoleTextFormatter())
    .CreateLogger();

using var listener = new ActivityListenerConfiguration().TraceTo(logger);

Starting and completing activities

ILogger.StartActivity() is the main SerilogTracing API for starting activities. It works on any ILogger, and the span generated by the activity will be written through that logger, receiving the same enrichment and filtering as any other log event.

using var activity = Log.Logger.StartActivity("Check {Host}", "example.com");

StartActivity accepts a message template, just like Serilog, and you can capture structured properties by including them in the template.

The object returned from StartActivity() is a LoggerActivity, to which you can add additional structured data using AddProperty().

The LoggerActivity implements IDisposable, and if you let the activity be disposed normally, it will record the activity as complete, and write a span through the underlying ILogger.

In the example, because the activity needs to be completed before the Log.CloseAndFlushAsync() call at the end, we call Complete() explicitly on the success path:

try
{
    // ...
    activity.Complete();
}
catch (Exception ex)
{
    activity.Complete(LogEventLevel.Fatal, ex);
}

On the failure path, we call the overload of Complete() that accepts a level and exception, to mark the activity as failed and use the specified level for the generated log event.

Tracing-enabled sinks

These sinks have been built or modified to work well with tracing back-ends:

  • Serilog.Sinks.Seq - call WriteTo.Seq() to send logs and traces to Seq; use Enrich.WithProperty("Application", "your app") to show service names in traces.
  • Serilog.Sinks.OpenTelemetry — call WriteTo.OpenTelemetry() to send traces and logs using OTLP.
  • SerilogTracing.Sinks.Zipkin - call WriteTo.Zipkin() to send traces to Zipkin; logs are ignored by this sink.

To add tracing support to an existing sink, see how activities are mapped onto LogEvents.

Adding instrumentation for ASP.NET Core requests

If you're writing an ASP.NET Core application, you'll notice that the spans generated in response to web requests have very generic names, like HttpRequestIn. To fix that, first add SerilogTracing.Instrumentation.AspNetCore:

dotnet add package SerilogTracing.Instrumentation.AspNetCore --prerelease

Then add Instrument.AspNetCoreRequests() to your ActivityListenerConfiguration:

using var listener = new ActivityListenerConfiguration()
    .Instrument.AspNetCoreRequests()
    .TraceToSharedLogger();

Incoming traceparent headers

HTTP requests received by ASP.NET Core may contain a header with the trace id, span id, and sampling decision made for the active span in the calling application. How this header is used can be configured with HttpRequestInActivityInstrumentationOptions.IncomingTraceParent:

using var listener = new ActivityListenerConfiguration()
    .Instrument.AspNetCoreRequests(opts =>
    {
        opts.IncomingTraceParent = IncomingTraceParent.Trust;
    })
    .TraceToSharedLogger();

The supported options are:

  • IncomingTraceParent.Accept (default) — the parent's trace and span ids will be used, but the sampling decision will be ignored; this reveals the presence of incoming tracing information while preventing callers from controlling whether data is recorded
  • IncomingTraceParent.Ignore — no information about the parent span will be preserved; this is the appropriate option for most public or Internet-facing sites and services
  • IncomingTraceParent.Trust — use the parent's trace and span ids, and respect the parent's sampling decision; this is the appropriate option for many internal services, since it allows system-wide sampling and consistent, detailed traces

See the section Sampling below for more information on how sampling works in SerilogTracing.

Adding instrumentation for HttpClient requests

HttpClient requests are instrumented by default. To configure the way HttpClient requests are recorded as spans, remove the default instrumentation and add HttpClient instrumentation explicitly:

using var listener = new ActivityListenerConfiguration()
    .Instrument.WithDefaultInstrumentation(false)
    .Instrument.HttpClientRequests(opts => opts.MessageTemplate = "Hello, world!")
    .TraceToSharedLogger();

The message template for spans, and mappings from HttpRequestMessage and HttpResponseMessage into log event properties and the completion level can be configured.

Adding instrumentation for Microsoft.Data.SqlClient commands

Microsoft's client library for SQL Server doesn't generate spans by default. To turn on tracing of database commands, install SerilogTracing.Instrumentation.SqlClient:

dotnet add package SerilogTracing.Instrumentation.SqlClient --prerelease

Then add Instrument.SqlClientCommands() to your ActivityListenerConfiguration:

using var listener = new ActivityListenerConfiguration()
    .Instrument.SqlClientCommands()
    .TraceToSharedLogger();

Adding instrumentation for Npgsql commands

Npgsql is internally instrumented using System.Diagnostics.Activity, so no additional packages or steps are required to enable instrumentation of Npgsql commands. If you're missing spans from Npgsql, check that the "Npgsql" namespace isn't suppressed by your MinimumLevel.Override() configuration.

Formatting output

SerilogTracing includes extensions to Serilog.Expressions aimed at producing useful text and JSON output from spans:

dotnet add package SerilogTracing.Expressions --prerelease

For console output, Formatters.CreateConsoleTextFormatter() provides span timings in a pleasant ANSI-colored format:

Log.Logger = new LoggerConfiguration()
    // The `Formatters` class is from `SerilogTracing.Expressions`
    .WriteTo.Console(Formatters.CreateConsoleTextFormatter(TemplateTheme.Code))
    .CreateLogger();

Alternatively, TracingNameResolver can be used with ExpressionTemplate to create text or JSON output. The example above expands into the (admittedly quite dense) template below:

var formatter = new ExpressionTemplate(
    "[{@t:HH:mm:ss} {@l:u3}] " +
    "{#if IsRootSpan()}\u2514\u2500 {#else if IsSpan()}\u251c {#else if @sp is not null}\u2502 {#else}\u250A {#end}" +
    "{@m}" +
    "{#if IsSpan()} ({Milliseconds(Elapsed()):0.###} ms){#end}" +
    "\n" +
    "{@x}",
    theme: TemplateTheme.Code,
    nameResolver: new TracingNameResolver());

Log.Logger = new LoggerConfiguration()
    .WriteTo.Console(formatter)
    .CreateLogger();

For an example showing how to produce JSON with ExpressionTemplate, see the implementation of ZipkinSink in this repository, and this article introducing Serilog.Expressions JSON support.

Sampling

Sampling is a method of reducing stored data volumes by selectively recording traces. This is similar to levelling, but instead of turning individual span types on and off, sampling causes either all of the spans in a trace to be recorded, or none of them.

SerilogTracing implements two simple strategies via ActivityListenerConfiguration: Sample.AllTraces(), which records all traces (the default), and Sample.OneTraceIn(), which records a fixed proportion of possible traces:

// Record only every 1000th trace
using var listener = new ActivityListenerConfiguration()
    .Sample.OneTraceIn(1000)
    .TraceToSharedLogger();

More sophisticated sampling strategies can be plugged in through Sample.Using(). These behave like the raw System.Diagnostics.ActivityListener API, but only apply to root spans. Setting the ignoreParent method parameter to true can be used to exactly mimic the System.Diagnostics.ActivityListener behavior.

[!NOTE] Once a sampling decision has been made for the root activity in a trace, SerilogTracing's sampling infrastructure will ensure all child activities inherit that sampling decision, regardless of the sampling policy in use. This means that when sampling decisions are communicated by a remote caller, care should be taken to either discard or trust that caller's decision. See the section Adding instrumentation for ASP.NET Core requests for information on how to do this with SerilogTracing's ASP.NET Core integration.

Sampling does not affect the recording of log events: log events written during an un-sampled trace will still be recorded, and will carry trace and span ids even though the corresponding spans will be missing.

How an Activity becomes a LogEvent

SerilogTracing pipeline

Applications using SerilogTracing add tracing using ILogger.StartActivity(). These activities are always converted into LogEvents and emitted through the original ILogger that created them. .NET libraries and frameworks add tracing using System.Diagnostics.ActivitySources. These activities are also emitted as LogEvents when using SerilogTracing.ActivityListenerConfiguration.

Mapping trace concepts to event properties

Traces are collections of spans, connected by a common trace id. SerilogTracing maps the typical properties associated with a span onto Serilog LogEvent instances:

Span feature LogEvent property
Trace id TraceId
Span id SpanId
Parent id Properties["ParentSpanId"]
Kind Properties["SpanKind"]
Name MessageTemplate
Start Properties["SpanStartTimestamp"]
End Timestamp
Status Level
Status description or error event Exception
Tags Properties[*]

Levelling for external activity sources

SerilogTracing can consume activities from .NET itself, and libraries that don't themselves use SerilogTracing. By default, you'll see spans for all activities, from all sources, in your Serilog output.

To "turn down" the level of tracing performed by an external activity source, use SerilogTracing's InitialLevel configuration to set a level for spans from that source:

    .InitialLevel.Override("Npgsql", LogEventLevel.Debug)

In this example, when activities from the Npgsql activity source are assigned an initial level of Debug, they'll be suppressed unless your Serilog logger has debug logging enabled.

Why is this an initial level?

The initial level assigned to a source determines whether activities are created by the source. When the activity is completed, it may be recorded at a higher level; for example, a span created at an initial Information level may complete as an Error (but not at a lower level such as Debug, because doing so may suppress the span cause the trace hierarchy to become incoherent).

Recording Activity.Events

Activities produced by external .NET libraries may include one or more embedded ActivityEvents. By default, SerilogTracing ignores these, except in the case of exception events, which map to the LogEvent.Exception property.

To emit additional LogEvents for each embedded ActivityEvent, call ActivityEvents.AsLogEvents() on ActivityListenerConfiguration.

What's the relationship between SerilogTracing and OpenTelemetry?

OpenTelemetry is a project that combines a variety of telemetry data models, schemas, APIs, and SDKs. SerilogTracing, like Serilog itself, has no dependency on the OpenTelemetry SDK, but can output traces using the OpenTelemetry Protocol (OTLP). From the point of view of SerilogTracing, this is considered to be just one of many protocols and systems that exist in the wider Serilog ecosystem.

If you're working in an environment with deep investment in OpenTelemetry, you might consider using the OpenTelemetry .NET SDK instead of SerilogTracing. If you're seeking lightweight, deliberate instrumentation that has the same crafted feel and tight control offered by Serilog, you're in the right place.

Who is developing SerilogTracing?

SerilogTracing is an open source (Apache 2.0) project that welcomes your ideas and contributions. It's built by @nblumhardt (also a Serilog maintainer), @liammclennan and @kodraus from Datalust, the company behind Seq.

SerilogTracing is not an official Serilog or Datalust project, but our hope for it is that it can serve as a validation and a basis for deeper tracing support in Serilog in the future.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (8)

Showing the top 5 NuGet packages that depend on SerilogTracing:

Package Downloads
SerilogTracing.Instrumentation.AspNetCore

Package Description

SerilogTracing.Expressions

Package Description

SerilogTracing.Sinks.OpenTelemetry

Sends log events and traces to OTLP (gRPC or HTTP) endpoints. This package is obsolete; use Serilog.Sinks.OpenTelemetry v4.x or later instead.

SerilogTracing.Instrumentation.SqlClient

Package Description

SerilogTracing.Sinks.Seq

Package Description

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on SerilogTracing:

Repository Stars
datalust/seqcli
The Seq command-line client. Administer, log, ingest, search, from any OS.
Version Downloads Last updated
2.3.1 462 12/19/2024
2.3.1-dev-00396 41 12/19/2024
2.3.1-dev-00395 165 12/8/2024
2.3.1-dev-00393 134 12/8/2024
2.3.0 28,932 11/28/2024
2.3.0-dev-00387 140 11/28/2024
2.3.0-dev-00386 227 11/15/2024
2.3.0-dev-00384 146 11/15/2024
2.3.0-dev-00377 745 11/10/2024
2.3.0-dev-00376 150 11/10/2024
2.3.0-dev-00360 4,486 10/18/2024
2.2.1-dev-00359 128 10/18/2024
2.2.1-dev-00356 455 10/14/2024
2.2.0 57,265 10/14/2024
2.2.0-dev-00353 165 10/10/2024
2.2.0-dev-00352 158 10/10/2024
2.1.3-dev-00351 167 10/10/2024
2.1.2 18,845 10/8/2024
2.1.2-dev-00345 159 10/8/2024
2.1.2-dev-00344 160 10/8/2024
2.1.2-dev-00342 288 10/8/2024
2.1.2-dev-00339 146 10/4/2024
2.1.2-dev-00336 174 10/2/2024
2.1.1 23,764 10/2/2024
2.1.1-dev-00332 174 10/2/2024
2.1.1-dev-00331 149 10/2/2024
2.1.1-dev-00324 822 7/29/2024
2.1.0 50,516 7/29/2024
2.1.0-dev-00322 135 7/29/2024
2.1.0-dev-00321 111 7/29/2024
2.1.0-dev-00320 130 7/29/2024
2.1.0-dev-00319 124 7/29/2024
2.1.0-dev-00317 243 7/24/2024
2.1.0-dev-00313 273 7/22/2024
2.0.1-dev-00312 201 7/22/2024
2.0.0 85,316 6/4/2024
2.0.0-dev-00306 226 6/3/2024
2.0.0-dev-00305 246 6/3/2024
2.0.0-dev-00304 259 6/1/2024
2.0.0-dev-00303 253 6/1/2024
1.1.0 46,733 5/2/2024
1.1.0-dev-00298 217 5/24/2024
1.1.0-dev-00297 234 5/24/2024
1.1.0-dev-00296 228 5/24/2024
1.1.0-dev-00295 188 5/16/2024
1.1.0-dev-00292 233 5/10/2024
1.1.0-dev-00287 266 5/1/2024
1.1.0-dev-00286 254 5/1/2024
1.1.0-dev-00283 253 4/30/2024
1.1.0-dev-00282 258 4/30/2024
1.0.1 13,919 4/18/2024
1.0.1-dev-00280 256 4/30/2024
1.0.1-dev-00276 237 4/18/2024
1.0.1-dev-00275 218 4/18/2024
1.0.1-dev-00273 15,472 3/26/2024
1.0.1-dev-00267 55,043 3/11/2024
1.0.1-dev-00266 373 3/11/2024
1.0.1-dev-00264 394 3/10/2024
1.0.1-dev-00261 1,052 3/5/2024
1.0.0 24,322 3/3/2024
1.0.0-dev-00257 3,225 2/29/2024
1.0.0-dev-00256 238 2/29/2024
1.0.0-dev-00251 1,028 2/27/2024
1.0.0-dev-00249 214 2/26/2024
1.0.0-dev-00247 231 2/26/2024
1.0.0-dev-00246 254 2/24/2024
1.0.0-dev-00242 1,317 2/22/2024
1.0.0-dev-00240 263 2/21/2024
1.0.0-dev-00236 223 2/21/2024
1.0.0-dev-00233 1,977 2/12/2024
1.0.0-dev-00231 585 2/12/2024
1.0.0-dev-00229 261 2/12/2024
1.0.0-dev-00228 241 2/12/2024
1.0.0-dev-00227 246 2/12/2024
1.0.0-dev-00225 225 2/12/2024
1.0.0-dev-00214 664 2/10/2024
1.0.0-dev-00179 238 2/9/2024
1.0.0-dev-00167 203 2/8/2024
1.0.0-dev-00164 235 2/8/2024
1.0.0-dev-00159 257 2/8/2024
1.0.0-dev-00155 239 2/7/2024
1.0.0-dev-00150 244 2/7/2024
1.0.0-dev-00142 306 2/6/2024
1.0.0-dev-00138 236 2/6/2024
1.0.0-dev-00135 240 2/6/2024
1.0.0-dev-00134 242 2/6/2024
1.0.0-dev-00132 287 2/5/2024
1.0.0-dev-00127 211 2/5/2024
1.0.0-dev-00121 261 2/1/2024
1.0.0-dev-00118 233 2/1/2024
1.0.0-dev-00115 198 2/1/2024
1.0.0-dev-00113 221 2/1/2024
1.0.0-dev-00107 206 1/31/2024
1.0.0-dev-00103 246 1/30/2024
1.0.0-dev-00102 1,145 1/25/2024
1.0.0-dev-00100 407 1/24/2024
1.0.0-dev-00097 233 1/24/2024
1.0.0-dev-00090 394 1/24/2024
1.0.0-dev-00088 1,095 1/22/2024
1.0.0-dev-00087 249 1/19/2024
1.0.0-dev-00086 210 1/18/2024
1.0.0-dev-00082 182 1/17/2024
1.0.0-dev-00080 174 1/17/2024
1.0.0-dev-00079 173 1/17/2024
1.0.0-dev-00077 172 1/17/2024
1.0.0-dev-00076 177 1/17/2024
1.0.0-dev-00070 152 1/16/2024
1.0.0-dev-00067 175 1/16/2024
1.0.0-dev-00066 165 1/16/2024
1.0.0-dev-00055 274 1/11/2024
1.0.0-dev-00051 150 1/10/2024
1.0.0-dev-00049 117 1/9/2024
1.0.0-dev-00044 126 1/9/2024
1.0.0-dev-00039 180 1/4/2024
1.0.0-dev-00038 106 1/4/2024
1.0.0-dev-00037 121 1/3/2024
1.0.0-dev-00034 110 1/3/2024
1.0.0-dev-00031 105 1/2/2024
1.0.0-dev-00030 117 1/2/2024
1.0.0-dev-00022 625 12/4/2023
1.0.0-dev-00017 122 11/28/2023
1.0.0-dev-00016 165 11/15/2023
1.0.0-dev-00015 106 11/15/2023
1.0.0-dev-00011 127 11/10/2023
1.0.0-dev-00010 608 11/7/2023
1.0.0-dev-00009 98 11/5/2023