SerilogTracing.Sinks.OpenTelemetry 1.0.0-dev-00076

This is a prerelease version of SerilogTracing.Sinks.OpenTelemetry.
There is a newer version of this package available.
See the version list below for details.
dotnet add package SerilogTracing.Sinks.OpenTelemetry --version 1.0.0-dev-00076                
NuGet\Install-Package SerilogTracing.Sinks.OpenTelemetry -Version 1.0.0-dev-00076                
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.Sinks.OpenTelemetry" Version="1.0.0-dev-00076" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add SerilogTracing.Sinks.OpenTelemetry --version 1.0.0-dev-00076                
#r "nuget: SerilogTracing.Sinks.OpenTelemetry, 1.0.0-dev-00076"                
#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.Sinks.OpenTelemetry as a Cake Addin
#addin nuget:?package=SerilogTracing.Sinks.OpenTelemetry&version=1.0.0-dev-00076&prerelease

// Install SerilogTracing.Sinks.OpenTelemetry as a Cake Tool
#tool nuget:?package=SerilogTracing.Sinks.OpenTelemetry&version=1.0.0-dev-00076&prerelease                

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 was computed.  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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
2.2.0 708 10/14/2024
2.2.0-dev-00353 69 10/10/2024
2.2.0-dev-00352 63 10/10/2024
2.1.3-dev-00351 65 10/10/2024
2.1.2 294 10/8/2024
2.1.2-dev-00345 63 10/8/2024
2.1.2-dev-00344 65 10/8/2024
2.1.2-dev-00342 71 10/8/2024
2.1.2-dev-00339 66 10/4/2024
2.1.2-dev-00336 78 10/2/2024
2.1.1 336 10/2/2024
2.1.1-dev-00332 70 10/2/2024
2.1.1-dev-00331 75 10/2/2024
2.1.1-dev-00324 90 7/29/2024
2.1.0 9,576 7/29/2024
2.1.0-dev-00322 71 7/29/2024
2.1.0-dev-00321 64 7/29/2024
2.1.0-dev-00320 66 7/29/2024
2.1.0-dev-00319 67 7/29/2024
2.1.0-dev-00317 79 7/24/2024
2.1.0-dev-00313 121 7/22/2024
2.0.1-dev-00312 73 7/22/2024
2.0.0 2,443 6/4/2024
2.0.0-dev-00306 97 6/3/2024
2.0.0-dev-00305 93 6/3/2024
2.0.0-dev-00304 94 6/1/2024
2.0.0-dev-00303 90 6/1/2024
1.1.0 963 5/2/2024
1.1.0-dev-00298 91 5/24/2024
1.1.0-dev-00297 85 5/24/2024
1.1.0-dev-00296 85 5/24/2024
1.1.0-dev-00295 88 5/16/2024
1.1.0-dev-00292 98 5/10/2024
1.1.0-dev-00287 91 5/1/2024
1.1.0-dev-00286 85 5/1/2024
1.1.0-dev-00283 99 4/30/2024
1.1.0-dev-00282 91 4/30/2024
1.0.1 3,382 4/18/2024
1.0.1-dev-00280 88 4/30/2024
1.0.1-dev-00276 88 4/18/2024
1.0.1-dev-00275 86 4/18/2024
1.0.1-dev-00273 15,265 3/26/2024
1.0.1-dev-00267 99 3/11/2024
1.0.1-dev-00266 97 3/11/2024
1.0.1-dev-00264 103 3/10/2024
1.0.1-dev-00261 92 3/5/2024
1.0.0 5,631 3/3/2024
1.0.0-dev-00257 105 2/29/2024
1.0.0-dev-00256 104 2/29/2024
1.0.0-dev-00251 143 2/27/2024
1.0.0-dev-00249 94 2/26/2024
1.0.0-dev-00247 84 2/26/2024
1.0.0-dev-00246 118 2/24/2024
1.0.0-dev-00242 90 2/22/2024
1.0.0-dev-00240 125 2/21/2024
1.0.0-dev-00236 106 2/21/2024
1.0.0-dev-00233 762 2/12/2024
1.0.0-dev-00231 96 2/12/2024
1.0.0-dev-00229 113 2/12/2024
1.0.0-dev-00228 103 2/12/2024
1.0.0-dev-00227 104 2/12/2024
1.0.0-dev-00225 89 2/12/2024
1.0.0-dev-00214 101 2/10/2024
1.0.0-dev-00179 106 2/9/2024
1.0.0-dev-00167 86 2/8/2024
1.0.0-dev-00164 101 2/8/2024
1.0.0-dev-00159 100 2/8/2024
1.0.0-dev-00155 107 2/7/2024
1.0.0-dev-00150 92 2/7/2024
1.0.0-dev-00142 95 2/6/2024
1.0.0-dev-00138 104 2/6/2024
1.0.0-dev-00135 98 2/6/2024
1.0.0-dev-00134 117 2/6/2024
1.0.0-dev-00132 93 2/5/2024
1.0.0-dev-00127 114 2/5/2024
1.0.0-dev-00121 112 2/1/2024
1.0.0-dev-00118 101 2/1/2024
1.0.0-dev-00115 77 2/1/2024
1.0.0-dev-00113 102 2/1/2024
1.0.0-dev-00107 97 1/31/2024
1.0.0-dev-00103 109 1/30/2024
1.0.0-dev-00102 862 1/25/2024
1.0.0-dev-00100 104 1/24/2024
1.0.0-dev-00097 107 1/24/2024
1.0.0-dev-00090 84 1/24/2024
1.0.0-dev-00088 158 1/22/2024
1.0.0-dev-00087 100 1/19/2024
1.0.0-dev-00086 94 1/18/2024
1.0.0-dev-00082 113 1/17/2024
1.0.0-dev-00080 86 1/17/2024
1.0.0-dev-00079 96 1/17/2024
1.0.0-dev-00077 94 1/17/2024
1.0.0-dev-00076 100 1/17/2024