SerilogTracing.Sinks.OpenTelemetry 1.0.0-dev-00138

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-00138                
NuGet\Install-Package SerilogTracing.Sinks.OpenTelemetry -Version 1.0.0-dev-00138                
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-00138" />                
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-00138                
#r "nuget: SerilogTracing.Sinks.OpenTelemetry, 1.0.0-dev-00138"                
#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-00138&prerelease

// Install SerilogTracing.Sinks.OpenTelemetry as a Cake Tool
#tool nuget:?package=SerilogTracing.Sinks.OpenTelemetry&version=1.0.0-dev-00138&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. Most sinks will currently flatten traces into individual spans, but it's easy to add full tracing support to sinks with capable back-ends, and the project ships tracing-enabled sinks for OpenTelemetry, Seq, and Zipkin.

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 --prerelease
dotnet add package SerilogTracing.Expressions --prerelease
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 _ = new TracingConfiguration().TraceToSharedLogger();

using var activity = Log.Logger.StartActivity("Check {Host}", "example.com");
try
{
    var client = new HttpClient();
    var content = 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 TracingConfiguration.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 _ = new TracingConfiguration().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 _ = new TracingConfiguration().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:

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

Adding instrumentation for ASP.NET Core

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 TracingConfiguration:

using var _ = new TracingConfiguration()
    .Instrument.AspNetCoreRequests()
    .TraceToSharedLogger();

Adding instrumentation for Microsoft.Data.SqlClient

Microsoft's client libraray 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 TracingConfiguration:

using var _ = new TracingConfiguration()
    .Instrument.SqlClientCommands()
    .TraceToSharedLogger();

How are traces represented as LogEvents?

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"]
Name MessageTemplate
Start Properties["SpanStartTimestamp"]
End Timestamp
Status Level
Status description or error event Exception
Tags Properties[*]

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.

SerilogTracing.Sinks.OpenTelemetry

SerilogTracing includes a fork of Serilog.Sinks.OpenTelemetry. This is necessary (for now) because Serilog.Sinks.OpenTelemetry only supports the OTLP logs protocol: SerilogTracing.Sinks.OpenTelemetry extends this with support for OTLP traces.

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

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 3,301 10/14/2024
2.2.0-dev-00353 78 10/10/2024
2.2.0-dev-00352 72 10/10/2024
2.1.3-dev-00351 73 10/10/2024
2.1.2 429 10/8/2024
2.1.2-dev-00345 73 10/8/2024
2.1.2-dev-00344 74 10/8/2024
2.1.2-dev-00342 76 10/8/2024
2.1.2-dev-00339 73 10/4/2024
2.1.2-dev-00336 83 10/2/2024
2.1.1 390 10/2/2024
2.1.1-dev-00332 75 10/2/2024
2.1.1-dev-00331 82 10/2/2024
2.1.1-dev-00324 95 7/29/2024
2.1.0 15,303 7/29/2024
2.1.0-dev-00322 76 7/29/2024
2.1.0-dev-00321 71 7/29/2024
2.1.0-dev-00320 71 7/29/2024
2.1.0-dev-00319 72 7/29/2024
2.1.0-dev-00317 85 7/24/2024
2.1.0-dev-00313 126 7/22/2024
2.0.1-dev-00312 78 7/22/2024
2.0.0 2,875 6/4/2024
2.0.0-dev-00306 102 6/3/2024
2.0.0-dev-00305 98 6/3/2024
2.0.0-dev-00304 99 6/1/2024
2.0.0-dev-00303 96 6/1/2024
1.1.0 1,078 5/2/2024
1.1.0-dev-00298 98 5/24/2024
1.1.0-dev-00297 92 5/24/2024
1.1.0-dev-00296 92 5/24/2024
1.1.0-dev-00295 95 5/16/2024
1.1.0-dev-00292 103 5/10/2024
1.1.0-dev-00287 96 5/1/2024
1.1.0-dev-00286 92 5/1/2024
1.1.0-dev-00283 108 4/30/2024
1.1.0-dev-00282 98 4/30/2024
1.0.1 3,491 4/18/2024
1.0.1-dev-00280 95 4/30/2024
1.0.1-dev-00276 97 4/18/2024
1.0.1-dev-00275 95 4/18/2024
1.0.1-dev-00273 15,272 3/26/2024
1.0.1-dev-00267 105 3/11/2024
1.0.1-dev-00266 106 3/11/2024
1.0.1-dev-00264 110 3/10/2024
1.0.1-dev-00261 97 3/5/2024
1.0.0 6,589 3/3/2024
1.0.0-dev-00257 110 2/29/2024
1.0.0-dev-00256 109 2/29/2024
1.0.0-dev-00251 149 2/27/2024
1.0.0-dev-00249 99 2/26/2024
1.0.0-dev-00247 90 2/26/2024
1.0.0-dev-00246 124 2/24/2024
1.0.0-dev-00242 96 2/22/2024
1.0.0-dev-00240 133 2/21/2024
1.0.0-dev-00236 112 2/21/2024
1.0.0-dev-00233 776 2/12/2024
1.0.0-dev-00231 106 2/12/2024
1.0.0-dev-00229 129 2/12/2024
1.0.0-dev-00228 111 2/12/2024
1.0.0-dev-00227 114 2/12/2024
1.0.0-dev-00225 101 2/12/2024
1.0.0-dev-00214 109 2/10/2024
1.0.0-dev-00179 114 2/9/2024
1.0.0-dev-00167 94 2/8/2024
1.0.0-dev-00164 109 2/8/2024
1.0.0-dev-00159 106 2/8/2024
1.0.0-dev-00155 111 2/7/2024
1.0.0-dev-00150 96 2/7/2024
1.0.0-dev-00142 103 2/6/2024
1.0.0-dev-00138 108 2/6/2024
1.0.0-dev-00135 102 2/6/2024
1.0.0-dev-00134 125 2/6/2024
1.0.0-dev-00132 99 2/5/2024
1.0.0-dev-00127 118 2/5/2024
1.0.0-dev-00121 116 2/1/2024
1.0.0-dev-00118 105 2/1/2024
1.0.0-dev-00115 81 2/1/2024
1.0.0-dev-00113 106 2/1/2024
1.0.0-dev-00107 101 1/31/2024
1.0.0-dev-00103 113 1/30/2024
1.0.0-dev-00102 866 1/25/2024
1.0.0-dev-00100 112 1/24/2024
1.0.0-dev-00097 113 1/24/2024
1.0.0-dev-00090 88 1/24/2024
1.0.0-dev-00088 162 1/22/2024
1.0.0-dev-00087 104 1/19/2024
1.0.0-dev-00086 98 1/18/2024
1.0.0-dev-00082 117 1/17/2024
1.0.0-dev-00080 90 1/17/2024
1.0.0-dev-00079 102 1/17/2024
1.0.0-dev-00077 102 1/17/2024
1.0.0-dev-00076 104 1/17/2024