SerilogTracing 1.0.0-dev-00031

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-00031
                    
NuGet\Install-Package SerilogTracing -Version 1.0.0-dev-00031
                    
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-00031" />
                    
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-00031" />
                    
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-00031
                    
#r "nuget: SerilogTracing, 1.0.0-dev-00031"
                    
#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-00031
                    
#: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-00031&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=SerilogTracing&version=1.0.0-dev-00031&prerelease
                    
Install as a Cake Tool

SerilogTracing

An experimental Serilog extension for producing and capturing hierarchical traces.

This is the logical successor to SerilogTimings, which provides very similar functionality, but emits plain log events rather than 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:

A screenshot of Seq showing output from the included Example application.

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 ParentSpanId and SpanStartTimestamp properties to represent the parts of a span not already covered by the other parts of the LogEvent.

SerilogTracing needs to hook into the logging pipeline at creation time; currently this must be done using:

Log.Logger = new LoggerConfiguration()
    ... // Other configuration as usual, then:
    .CreateTracingLogger();

In addition to generating spans, SerilogTracing also consumes spans generated elsewhere in an application via the System.Diagnostics.Activity APIs, such as those produced by ASP.NET Core or HttpClient. Activity sources can be enabled or disabled using the logger's MinimumLevel.Override settings.

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

Starting, enriching, and completing activities

Activities are represented by LoggerActivity instances.

LoggerActivity has a simple lifetime:

  • The activity is started using one of the ILogger.StartActivity() extensions,
  • Properties are added to the activity using LoggerActivity.AddProperty(), and
  • The activity is completed either implicitly, by IDisposable.Dispose(), or explicitly using LoggerActivity.Complete().

LoggerActivity.Complete() accepts optional LogEventLevel and Exception arguments.

Displaying output

Use the formatters provides by Serilog.Tracing.Formatting.DefaultFormatting to pretty-print spans as text, or serialize to JSON.

Configuring the activity listener

Activity sources can be enabled and disabled using the standard MinimumLevel.Override() mechanism.

Status

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).

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.

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.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 311,791 12/19/2024
2.3.1-dev-00396 197 12/19/2024
2.3.1-dev-00395 279 12/8/2024
2.3.1-dev-00393 171 12/8/2024
2.3.0 188,002 11/28/2024
2.3.0-dev-00387 171 11/28/2024
2.3.0-dev-00386 269 11/15/2024
2.3.0-dev-00384 179 11/15/2024
2.3.0-dev-00377 3,168 11/10/2024
2.3.0-dev-00376 188 11/10/2024
2.3.0-dev-00360 9,021 10/18/2024
2.2.1-dev-00359 162 10/18/2024
2.2.1-dev-00356 2,180 10/14/2024
2.2.0 161,350 10/14/2024
2.2.0-dev-00353 196 10/10/2024
2.2.0-dev-00352 184 10/10/2024
2.1.3-dev-00351 197 10/10/2024
2.1.2 23,979 10/8/2024
2.1.2-dev-00345 182 10/8/2024
2.1.2-dev-00344 206 10/8/2024
2.1.2-dev-00342 324 10/8/2024
2.1.2-dev-00339 180 10/4/2024
2.1.2-dev-00336 199 10/2/2024
2.1.1 90,726 10/2/2024
2.1.1-dev-00332 204 10/2/2024
2.1.1-dev-00331 179 10/2/2024
2.1.1-dev-00324 1,807 7/29/2024
2.1.0 85,766 7/29/2024
2.1.0-dev-00322 167 7/29/2024
2.1.0-dev-00321 130 7/29/2024
2.1.0-dev-00320 147 7/29/2024
2.1.0-dev-00319 145 7/29/2024
2.1.0-dev-00317 278 7/24/2024
2.1.0-dev-00313 302 7/22/2024
2.0.1-dev-00312 227 7/22/2024
2.0.0 109,168 6/4/2024
2.0.0-dev-00306 244 6/3/2024
2.0.0-dev-00305 264 6/3/2024
2.0.0-dev-00304 288 6/1/2024
2.0.0-dev-00303 287 6/1/2024
1.1.0 81,871 5/2/2024
1.1.0-dev-00298 245 5/24/2024
1.1.0-dev-00297 259 5/24/2024
1.1.0-dev-00296 263 5/24/2024
1.1.0-dev-00295 214 5/16/2024
1.1.0-dev-00292 260 5/10/2024
1.1.0-dev-00287 289 5/1/2024
1.1.0-dev-00286 279 5/1/2024
1.1.0-dev-00283 280 4/30/2024
1.1.0-dev-00282 288 4/30/2024
1.0.1 16,753 4/18/2024
1.0.1-dev-00280 283 4/30/2024
1.0.1-dev-00276 257 4/18/2024
1.0.1-dev-00275 239 4/18/2024
1.0.1-dev-00273 15,502 3/26/2024
1.0.1-dev-00267 63,045 3/11/2024
1.0.1-dev-00266 393 3/11/2024
1.0.1-dev-00264 596 3/10/2024
1.0.1-dev-00261 1,485 3/5/2024
1.0.0 33,766 3/3/2024
1.0.0-dev-00257 3,833 2/29/2024
1.0.0-dev-00256 260 2/29/2024
1.0.0-dev-00251 1,052 2/27/2024
1.0.0-dev-00249 237 2/26/2024
1.0.0-dev-00247 256 2/26/2024
1.0.0-dev-00246 282 2/24/2024
1.0.0-dev-00242 1,348 2/22/2024
1.0.0-dev-00240 293 2/21/2024
1.0.0-dev-00236 257 2/21/2024
1.0.0-dev-00233 1,997 2/12/2024
1.0.0-dev-00231 612 2/12/2024
1.0.0-dev-00229 282 2/12/2024
1.0.0-dev-00228 265 2/12/2024
1.0.0-dev-00227 274 2/12/2024
1.0.0-dev-00225 246 2/12/2024
1.0.0-dev-00214 686 2/10/2024
1.0.0-dev-00179 261 2/9/2024
1.0.0-dev-00167 227 2/8/2024
1.0.0-dev-00164 262 2/8/2024
1.0.0-dev-00159 277 2/8/2024
1.0.0-dev-00155 259 2/7/2024
1.0.0-dev-00150 262 2/7/2024
1.0.0-dev-00142 329 2/6/2024
1.0.0-dev-00138 261 2/6/2024
1.0.0-dev-00135 262 2/6/2024
1.0.0-dev-00134 265 2/6/2024
1.0.0-dev-00132 309 2/5/2024
1.0.0-dev-00127 236 2/5/2024
1.0.0-dev-00121 285 2/1/2024
1.0.0-dev-00118 251 2/1/2024
1.0.0-dev-00115 220 2/1/2024
1.0.0-dev-00113 249 2/1/2024
1.0.0-dev-00107 227 1/31/2024
1.0.0-dev-00103 263 1/30/2024
1.0.0-dev-00102 1,175 1/25/2024
1.0.0-dev-00100 428 1/24/2024
1.0.0-dev-00097 252 1/24/2024
1.0.0-dev-00090 435 1/24/2024
1.0.0-dev-00088 1,124 1/22/2024
1.0.0-dev-00087 272 1/19/2024
1.0.0-dev-00086 230 1/18/2024
1.0.0-dev-00082 201 1/17/2024
1.0.0-dev-00080 200 1/17/2024
1.0.0-dev-00079 194 1/17/2024
1.0.0-dev-00077 200 1/17/2024
1.0.0-dev-00076 197 1/17/2024
1.0.0-dev-00070 180 1/16/2024
1.0.0-dev-00067 197 1/16/2024
1.0.0-dev-00066 187 1/16/2024
1.0.0-dev-00055 301 1/11/2024
1.0.0-dev-00051 175 1/10/2024
1.0.0-dev-00049 138 1/9/2024
1.0.0-dev-00044 153 1/9/2024
1.0.0-dev-00039 203 1/4/2024
1.0.0-dev-00038 139 1/4/2024
1.0.0-dev-00037 143 1/3/2024
1.0.0-dev-00034 137 1/3/2024
1.0.0-dev-00031 133 1/2/2024
1.0.0-dev-00030 144 1/2/2024
1.0.0-dev-00022 646 12/4/2023
1.0.0-dev-00017 149 11/28/2023
1.0.0-dev-00016 191 11/15/2023
1.0.0-dev-00015 133 11/15/2023
1.0.0-dev-00011 158 11/10/2023
1.0.0-dev-00010 632 11/7/2023
1.0.0-dev-00009 124 11/5/2023