SerilogTracing 1.0.0-dev-00077

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

SerilogTracing

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 by .NET system libraries and packages through any Serilog sink,
  2. Generate rich traces using Serilog APIs and idioms, that can still be observed by other consumers of the .NET APIs,
  3. Introduce tracing gradually into applications already instrumented with Serilog.

Wt 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!

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), and
  • start time.

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 the ParentSpanId and SpanStartTimestamp properties.

SerilogTracing relies on the underlying .NET tracing infrastructure to propagate trace ids and record the parent-child relationships between spans.

The TracingConfiguration class from SerilogTracing is used for this:

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

// Tracing will be enabled until the returned handle is disposed.
using var _ = new TracingConfiguration()
    .EnableTracing();

In addition to generating spans, SerilogTracing 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.

SerilogTracing.Sinks.OpenTelemetry

SerilogTracing includes a fork of Serilog.Sinks.OpenTelemetry. This is necessary (for now) because Serilog.Sinks.OpenTelemetry only handles log signals. SerilogTrace.Sinks.OpenTelemetry also handles trace signals.

What about SerilogTimings?

SerilogTracing is the logical successor to SerilogTimings, which provides very similar functionality.

Like SerilogTimings, SerilogTracing can track the duration and status of an operation, and emit an event when the operation completes.

Unlike SerilogTimings, SerilogTracing:

  • can represent and capture hierarchical (parent/child) operations,
  • takes part in distributed traces, and
  • integrates with the tracing support provided by .NET itself and the rest of the package ecosystem.

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 204,099 12/19/2024
2.3.1-dev-00396 186 12/19/2024
2.3.1-dev-00395 262 12/8/2024
2.3.1-dev-00393 157 12/8/2024
2.3.0 159,864 11/28/2024
2.3.0-dev-00387 156 11/28/2024
2.3.0-dev-00386 252 11/15/2024
2.3.0-dev-00384 164 11/15/2024
2.3.0-dev-00377 2,635 11/10/2024
2.3.0-dev-00376 169 11/10/2024
2.3.0-dev-00360 9,008 10/18/2024
2.2.1-dev-00359 143 10/18/2024
2.2.1-dev-00356 1,954 10/14/2024
2.2.0 151,715 10/14/2024
2.2.0-dev-00353 181 10/10/2024
2.2.0-dev-00352 171 10/10/2024
2.1.3-dev-00351 180 10/10/2024
2.1.2 23,720 10/8/2024
2.1.2-dev-00345 171 10/8/2024
2.1.2-dev-00344 188 10/8/2024
2.1.2-dev-00342 304 10/8/2024
2.1.2-dev-00339 158 10/4/2024
2.1.2-dev-00336 188 10/2/2024
2.1.1 76,670 10/2/2024
2.1.1-dev-00332 189 10/2/2024
2.1.1-dev-00331 166 10/2/2024
2.1.1-dev-00324 1,760 7/29/2024
2.1.0 78,912 7/29/2024
2.1.0-dev-00322 155 7/29/2024
2.1.0-dev-00321 120 7/29/2024
2.1.0-dev-00320 141 7/29/2024
2.1.0-dev-00319 135 7/29/2024
2.1.0-dev-00317 257 7/24/2024
2.1.0-dev-00313 288 7/22/2024
2.0.1-dev-00312 219 7/22/2024
2.0.0 104,731 6/4/2024
2.0.0-dev-00306 235 6/3/2024
2.0.0-dev-00305 255 6/3/2024
2.0.0-dev-00304 269 6/1/2024
2.0.0-dev-00303 271 6/1/2024
1.1.0 76,145 5/2/2024
1.1.0-dev-00298 232 5/24/2024
1.1.0-dev-00297 246 5/24/2024
1.1.0-dev-00296 243 5/24/2024
1.1.0-dev-00295 200 5/16/2024
1.1.0-dev-00292 246 5/10/2024
1.1.0-dev-00287 278 5/1/2024
1.1.0-dev-00286 265 5/1/2024
1.1.0-dev-00283 264 4/30/2024
1.1.0-dev-00282 267 4/30/2024
1.0.1 16,147 4/18/2024
1.0.1-dev-00280 268 4/30/2024
1.0.1-dev-00276 246 4/18/2024
1.0.1-dev-00275 229 4/18/2024
1.0.1-dev-00273 15,490 3/26/2024
1.0.1-dev-00267 61,097 3/11/2024
1.0.1-dev-00266 383 3/11/2024
1.0.1-dev-00264 538 3/10/2024
1.0.1-dev-00261 1,428 3/5/2024
1.0.0 32,076 3/3/2024
1.0.0-dev-00257 3,738 2/29/2024
1.0.0-dev-00256 246 2/29/2024
1.0.0-dev-00251 1,041 2/27/2024
1.0.0-dev-00249 228 2/26/2024
1.0.0-dev-00247 245 2/26/2024
1.0.0-dev-00246 266 2/24/2024
1.0.0-dev-00242 1,336 2/22/2024
1.0.0-dev-00240 280 2/21/2024
1.0.0-dev-00236 240 2/21/2024
1.0.0-dev-00233 1,992 2/12/2024
1.0.0-dev-00231 596 2/12/2024
1.0.0-dev-00229 271 2/12/2024
1.0.0-dev-00228 252 2/12/2024
1.0.0-dev-00227 257 2/12/2024
1.0.0-dev-00225 237 2/12/2024
1.0.0-dev-00214 675 2/10/2024
1.0.0-dev-00179 249 2/9/2024
1.0.0-dev-00167 211 2/8/2024
1.0.0-dev-00164 246 2/8/2024
1.0.0-dev-00159 266 2/8/2024
1.0.0-dev-00155 248 2/7/2024
1.0.0-dev-00150 252 2/7/2024
1.0.0-dev-00142 317 2/6/2024
1.0.0-dev-00138 247 2/6/2024
1.0.0-dev-00135 249 2/6/2024
1.0.0-dev-00134 253 2/6/2024
1.0.0-dev-00132 295 2/5/2024
1.0.0-dev-00127 222 2/5/2024
1.0.0-dev-00121 270 2/1/2024
1.0.0-dev-00118 242 2/1/2024
1.0.0-dev-00115 209 2/1/2024
1.0.0-dev-00113 231 2/1/2024
1.0.0-dev-00107 215 1/31/2024
1.0.0-dev-00103 256 1/30/2024
1.0.0-dev-00102 1,159 1/25/2024
1.0.0-dev-00100 418 1/24/2024
1.0.0-dev-00097 243 1/24/2024
1.0.0-dev-00090 419 1/24/2024
1.0.0-dev-00088 1,112 1/22/2024
1.0.0-dev-00087 262 1/19/2024
1.0.0-dev-00086 219 1/18/2024
1.0.0-dev-00082 192 1/17/2024
1.0.0-dev-00080 187 1/17/2024
1.0.0-dev-00079 181 1/17/2024
1.0.0-dev-00077 183 1/17/2024
1.0.0-dev-00076 186 1/17/2024
1.0.0-dev-00070 161 1/16/2024
1.0.0-dev-00067 184 1/16/2024
1.0.0-dev-00066 173 1/16/2024
1.0.0-dev-00055 283 1/11/2024
1.0.0-dev-00051 159 1/10/2024
1.0.0-dev-00049 126 1/9/2024
1.0.0-dev-00044 135 1/9/2024
1.0.0-dev-00039 189 1/4/2024
1.0.0-dev-00038 115 1/4/2024
1.0.0-dev-00037 130 1/3/2024
1.0.0-dev-00034 120 1/3/2024
1.0.0-dev-00031 116 1/2/2024
1.0.0-dev-00030 129 1/2/2024
1.0.0-dev-00022 635 12/4/2023
1.0.0-dev-00017 132 11/28/2023
1.0.0-dev-00016 176 11/15/2023
1.0.0-dev-00015 116 11/15/2023
1.0.0-dev-00011 142 11/10/2023
1.0.0-dev-00010 616 11/7/2023
1.0.0-dev-00009 107 11/5/2023