SerilogTracing 1.0.0-dev-00010

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 1.0.0-dev-00010
                    
NuGet\Install-Package SerilogTracing -Version 1.0.0-dev-00010
                    
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="1.0.0-dev-00010" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="SerilogTracing" Version="1.0.0-dev-00010" />
                    
Directory.Packages.props
<PackageReference Include="SerilogTracing" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add SerilogTracing --version 1.0.0-dev-00010
                    
#r "nuget: SerilogTracing, 1.0.0-dev-00010"
                    
#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.
#:package SerilogTracing@1.0.0-dev-00010
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=SerilogTracing&version=1.0.0-dev-00010&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=SerilogTracing&version=1.0.0-dev-00010&prerelease
                    
Install as a Cake Tool

SerilogTracing

⚠ This project isn't ready to check out just yet, please drop by again soon.

An experimental Serilog extension for producing and capturing hierarchical traces.

What is SerilogTracing?

SerilogTracing integrates Serilog with the System.Diagnostics.Activity* types provided by the .NET BCL. This makes it possible to:

  1. Record traces generated using the .NET APIs through Serilog sinks, and
  2. Generate rich traces using Serilog APIs and idioms, that can still be observed by other consumers of the .NET APIs.

There are two main scenarios where these capabilities combine usefully.

First, at development time, routing trace information through Serilog means that all of the beautiful, developer-friendly Serilog outputs can be used for simple local feedback.

Here's what that looks like, routed through Serilog's console sink:

A screenshot of Windows Terminal showing output from the included Example application.

The example is using Serilog's ExpressionTemplate to annotate each span in the trace with timing information. The layout is fully configurable - check out Program.cs in the included example project - so let your ASCII artistry run wild!

Second, in production, Serilog's existing configuration, enrichment, filtering, formatting, and output facilities can potentially provide a flexible mechanism for emitting trace data to a wide range of targets.

Notably, any system that accepts traces in text or JSON format should be an easy target for SerilogTracing and a Serilog sink; here's Seq showing traces delivered using the production Serilog.Sinks.Seq package and a custom ITextFormatter implemented with ExpressionTemplate:

![]

How does it work?

And what do we mean by "tracing"?

A trace is just a collection of spans, and a span is just an event that carries a:

  • trace id,
  • span id,
  • parent span id (optional),
  • start time, and
  • duration.

SerilogTracing generates spans using extension methods on ILogger:

using var activity = logger.StartActivity("Compute {A} + {B}", a, b);
// ... on `Dispose()` the activity will be recorded as a span

The spans generated by SerilogTracing are converted into Serilog LogEvents and routed through the logger. There's nothing particularly special about these events, except that they add @ps (parent span id) and @st (span start time) properties to represent the parts of a span not already covered by the other parts of the LogEvent.

In addition to generating spans, SerilogTracing can also consume spans generated elsewhere in an application via the System.Diagnostics.Activity APIs, such as those produced by ASP.NET Core or HttpClient.

This is done using SerilogActivityListener:

using var _ = SerilogActivityListener.Create();
// ... spans start flowing through `Log.Logger`

Finally, SerilogTracing includes some examples showing how the resulting LogEvents can be formatted for various trace-aware outputs.

Starting, enriching, and completing activities

TBA.

Configuring the activity listener

TBA. Need a discussion of how sources can be filtered or ignored using MinimumLevel.Override on the target logger.

Formatting spans with ExpressionTemplate

TBA.

Status and known limitations

This project is experimental. It's not a part of Serilog, not maintained by the Serilog maintainers, and might not evolve in any particular way: there's currently no plan to integrate this functionality directly into Serilog. (Having said that, this project is a vehicle to explore those possibilities).

Other limitations generally stem from the project's immaturity or implementation state: if something listed here interests you, feel free to hack away on a fork and propose any useful changes you can come up with!

  • Not much thought has been given to sampling.
  • Non-W3C id formats haven't been considered at all.
  • Activities generated by SerilogTracing won't expose source names based on ForContext<T>() to other ActivityListeners, instead marking the activities as from the generic Serilog.Core.Logger source. To expose richer source names, use the generic overload of the StartActivity extension method.
  • Serilog.Sinks.OpenTelemetry, which should be a useful output for SerilogTracing, doesn't yet include any support for emitting spans over OTLP.
Product Compatible and additional computed target framework versions.
.NET 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.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net6.0

  • net8.0

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.Instrumentation.SqlClient

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.Sinks.Zipkin

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 449,824 12/19/2024
2.3.1-dev-00396 207 12/19/2024
2.3.1-dev-00395 289 12/8/2024
2.3.1-dev-00393 178 12/8/2024
2.3.0 204,427 11/28/2024
2.3.0-dev-00387 177 11/28/2024
2.3.0-dev-00386 278 11/15/2024
2.3.0-dev-00384 190 11/15/2024
2.3.0-dev-00377 4,936 11/10/2024
2.3.0-dev-00376 193 11/10/2024
2.3.0-dev-00360 9,029 10/18/2024
2.2.1-dev-00359 170 10/18/2024
2.2.1-dev-00356 2,310 10/14/2024
2.2.0 170,753 10/14/2024
2.2.0-dev-00353 201 10/10/2024
2.2.0-dev-00352 194 10/10/2024
2.1.3-dev-00351 205 10/10/2024
2.1.2 24,104 10/8/2024
2.1.2-dev-00345 192 10/8/2024
2.1.2-dev-00344 215 10/8/2024
2.1.2-dev-00342 334 10/8/2024
2.1.2-dev-00339 188 10/4/2024
2.1.2-dev-00336 206 10/2/2024
2.1.1 103,928 10/2/2024
2.1.1-dev-00332 216 10/2/2024
2.1.1-dev-00331 190 10/2/2024
2.1.1-dev-00324 1,859 7/29/2024
2.1.0 91,743 7/29/2024
2.1.0-dev-00322 175 7/29/2024
2.1.0-dev-00321 133 7/29/2024
2.1.0-dev-00320 150 7/29/2024
2.1.0-dev-00319 154 7/29/2024
2.1.0-dev-00317 283 7/24/2024
2.1.0-dev-00313 309 7/22/2024
2.0.1-dev-00312 235 7/22/2024
2.0.0 114,699 6/4/2024
2.0.0-dev-00306 252 6/3/2024
2.0.0-dev-00305 271 6/3/2024
2.0.0-dev-00304 298 6/1/2024
2.0.0-dev-00303 295 6/1/2024
1.1.0 88,663 5/2/2024
1.1.0-dev-00298 251 5/24/2024
1.1.0-dev-00297 264 5/24/2024
1.1.0-dev-00296 269 5/24/2024
1.1.0-dev-00295 221 5/16/2024
1.1.0-dev-00292 269 5/10/2024
1.1.0-dev-00287 301 5/1/2024
1.1.0-dev-00286 288 5/1/2024
1.1.0-dev-00283 289 4/30/2024
1.1.0-dev-00282 299 4/30/2024
1.0.1 17,196 4/18/2024
1.0.1-dev-00280 291 4/30/2024
1.0.1-dev-00276 260 4/18/2024
1.0.1-dev-00275 248 4/18/2024
1.0.1-dev-00273 15,512 3/26/2024
1.0.1-dev-00267 64,361 3/11/2024
1.0.1-dev-00266 402 3/11/2024
1.0.1-dev-00264 727 3/10/2024
1.0.1-dev-00261 1,540 3/5/2024
1.0.0 34,936 3/3/2024
1.0.0-dev-00257 3,882 2/29/2024
1.0.0-dev-00256 273 2/29/2024
1.0.0-dev-00251 1,058 2/27/2024
1.0.0-dev-00249 247 2/26/2024
1.0.0-dev-00247 262 2/26/2024
1.0.0-dev-00246 291 2/24/2024
1.0.0-dev-00242 1,356 2/22/2024
1.0.0-dev-00240 302 2/21/2024
1.0.0-dev-00236 265 2/21/2024
1.0.0-dev-00233 2,000 2/12/2024
1.0.0-dev-00231 624 2/12/2024
1.0.0-dev-00229 285 2/12/2024
1.0.0-dev-00228 274 2/12/2024
1.0.0-dev-00227 281 2/12/2024
1.0.0-dev-00225 254 2/12/2024
1.0.0-dev-00214 695 2/10/2024
1.0.0-dev-00179 268 2/9/2024
1.0.0-dev-00167 237 2/8/2024
1.0.0-dev-00164 269 2/8/2024
1.0.0-dev-00159 285 2/8/2024
1.0.0-dev-00155 268 2/7/2024
1.0.0-dev-00150 265 2/7/2024
1.0.0-dev-00142 341 2/6/2024
1.0.0-dev-00138 268 2/6/2024
1.0.0-dev-00135 271 2/6/2024
1.0.0-dev-00134 272 2/6/2024
1.0.0-dev-00132 317 2/5/2024
1.0.0-dev-00127 244 2/5/2024
1.0.0-dev-00121 297 2/1/2024
1.0.0-dev-00118 256 2/1/2024
1.0.0-dev-00115 229 2/1/2024
1.0.0-dev-00113 257 2/1/2024
1.0.0-dev-00107 234 1/31/2024
1.0.0-dev-00103 266 1/30/2024
1.0.0-dev-00102 1,184 1/25/2024
1.0.0-dev-00100 435 1/24/2024
1.0.0-dev-00097 260 1/24/2024
1.0.0-dev-00090 446 1/24/2024
1.0.0-dev-00088 1,136 1/22/2024
1.0.0-dev-00087 276 1/19/2024
1.0.0-dev-00086 238 1/18/2024
1.0.0-dev-00082 209 1/17/2024
1.0.0-dev-00080 211 1/17/2024
1.0.0-dev-00079 200 1/17/2024
1.0.0-dev-00077 206 1/17/2024
1.0.0-dev-00076 205 1/17/2024
1.0.0-dev-00070 190 1/16/2024
1.0.0-dev-00067 206 1/16/2024
1.0.0-dev-00066 194 1/16/2024
1.0.0-dev-00055 304 1/11/2024
1.0.0-dev-00051 186 1/10/2024
1.0.0-dev-00049 145 1/9/2024
1.0.0-dev-00044 163 1/9/2024
1.0.0-dev-00039 212 1/4/2024
1.0.0-dev-00038 147 1/4/2024
1.0.0-dev-00037 151 1/3/2024
1.0.0-dev-00034 145 1/3/2024
1.0.0-dev-00031 139 1/2/2024
1.0.0-dev-00030 151 1/2/2024
1.0.0-dev-00022 655 12/4/2023
1.0.0-dev-00017 156 11/28/2023
1.0.0-dev-00016 200 11/15/2023
1.0.0-dev-00015 140 11/15/2023
1.0.0-dev-00011 161 11/10/2023
1.0.0-dev-00010 636 11/7/2023
1.0.0-dev-00009 132 11/5/2023