SerilogTracing.Sinks.OpenTelemetry
1.0.0-dev-00088
See the version list below for details.
dotnet add package SerilogTracing.Sinks.OpenTelemetry --version 1.0.0-dev-00088
NuGet\Install-Package SerilogTracing.Sinks.OpenTelemetry -Version 1.0.0-dev-00088
<PackageReference Include="SerilogTracing.Sinks.OpenTelemetry" Version="1.0.0-dev-00088" />
paket add SerilogTracing.Sinks.OpenTelemetry --version 1.0.0-dev-00088
#r "nuget: SerilogTracing.Sinks.OpenTelemetry, 1.0.0-dev-00088"
// Install SerilogTracing.Sinks.OpenTelemetry as a Cake Addin #addin nuget:?package=SerilogTracing.Sinks.OpenTelemetry&version=1.0.0-dev-00088&prerelease // Install SerilogTracing.Sinks.OpenTelemetry as a Cake Tool #tool nuget:?package=SerilogTracing.Sinks.OpenTelemetry&version=1.0.0-dev-00088&prerelease
SerilogTracing
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:
The same trace displayed in Seq:
And in Zipkin:
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 SerilogTracing;
using SerilogTracing.Expressions;
Log.Logger = new LoggerConfiguration()
.WriteTo.Console(Formatters.CreateConsoleTextFormatter())
.CreateLogger();
using var _ = new TracingConfiguration().EnableTracing();
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 SerilogTracing;
using SerilogTracing.Expressions;
Log.Logger = new LoggerConfiguration()
.WriteTo.Console(Formatters.CreateConsoleTextFormatter())
.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.EnableTracing()
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().EnableTracing();
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.
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
— callWriteTo.OpenTelemetry()
and passtracingEndpoint
along withlogsEndpoint
to send traces and logs using OTLP.SerilogTracing.Sinks.Seq
- callWriteTo.SeqTracing()
to send logs and traces to Seq; useEnrich.WithProperty("Application", "your app")
to show service names in traces.SerilogTracing.Sinks.Zipkin
- callWriteTo.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
Then add Instrument.AspNetCoreRequests()
to your TracingConfiguration
:
using var _ = new TracingConfiguration()
.Instrument.AspNetCoreRequests()
.EnableTracing();
How are traces represented as LogEvent
s?
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 produce OpenTelemetry-compatible data 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 | Versions 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. |
-
.NETStandard 2.0
- Google.Protobuf (>= 3.25.1)
- Grpc.Net.Client (>= 2.60.0)
- Serilog (>= 3.1.1)
- Serilog.Sinks.PeriodicBatching (>= 4.0.0-dev-00821)
- SerilogTracing (>= 1.0.0-dev-00088)
- System.Diagnostics.DiagnosticSource (>= 8.0.0)
-
net6.0
- Google.Protobuf (>= 3.25.1)
- Grpc.Net.Client (>= 2.60.0)
- Serilog (>= 3.1.1)
- Serilog.Sinks.PeriodicBatching (>= 4.0.0-dev-00821)
- SerilogTracing (>= 1.0.0-dev-00088)
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 |