SerilogTracing 2.1.1-dev-00324
dotnet add package SerilogTracing --version 2.1.1-dev-00324
NuGet\Install-Package SerilogTracing -Version 2.1.1-dev-00324
<PackageReference Include="SerilogTracing" Version="2.1.1-dev-00324" />
paket add SerilogTracing --version 2.1.1-dev-00324
#r "nuget: SerilogTracing, 2.1.1-dev-00324"
// Install SerilogTracing as a Cake Addin #addin nuget:?package=SerilogTracing&version=2.1.1-dev-00324&prerelease // Install SerilogTracing as a Cake Tool #tool nuget:?package=SerilogTracing&version=2.1.1-dev-00324&prerelease
SerilogTracing ![NuGet Version](https://img.shields.io/nuget/v/SerilogTracing.svg?style=flat)
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
dotnet add package SerilogTracing.Expressions
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 listener = new ActivityListenerConfiguration().TraceToSharedLogger();
using var activity = Log.Logger.StartActivity("Check {Host}", "example.com");
try
{
var client = new HttpClient();
var content = await 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 ActivityListenerConfiguration.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 listener = new ActivityListenerConfiguration().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 listener = new ActivityListenerConfiguration().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:
Serilog.Sinks.Seq
- callWriteTo.Seq()
to send logs and traces to Seq; useEnrich.WithProperty("Application", "your app")
to show service names in traces.Serilog.Sinks.OpenTelemetry
— callWriteTo.OpenTelemetry()
to send traces and logs using OTLP.SerilogTracing.Sinks.Zipkin
- callWriteTo.Zipkin()
to send traces to Zipkin; logs are ignored by this sink.
Adding instrumentation for ASP.NET Core requests
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 ActivityListenerConfiguration
:
using var listener = new ActivityListenerConfiguration()
.Instrument.AspNetCoreRequests()
.TraceToSharedLogger();
Adding instrumentation for HttpClient
requests
HttpClient
requests are instrumented by default. To configure the way HttpClient
requests are recorded as spans, remove the default instrumentation and add HttpClient
instrumentation explicitly:
using var listener = new ActivityListenerConfiguration()
.Instrument.WithDefaultInstrumentation(false)
.Instrument.HttpClientRequests(opts => opts.MessageTemplate = "Hello, world!")
.TraceToSharedLogger();
The message template for spans, and mappings from HttpRequestMessage
and HttpResponseMessage
into log event properties and the completion level can be configured.
Adding instrumentation for Microsoft.Data.SqlClient
commands
Microsoft's client library 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 ActivityListenerConfiguration
:
using var listener = new ActivityListenerConfiguration()
.Instrument.SqlClientCommands()
.TraceToSharedLogger();
Adding instrumentation for Npgsql
commands
Npgsql is internally instrumented using System.Diagnostics.Activity
, so no additional packages or steps are required to enable instrumentation of Npgsql commands. If you're missing spans from Npgsql, check that the "Npgsql"
namespace isn't suppressed by your MinimumLevel.Override()
configuration.
Formatting output
SerilogTracing includes extensions to Serilog.Expressions aimed at producing useful text and JSON output from spans:
dotnet add package SerilogTracing.Expressions --prerelease
For console output, Formatters.CreateConsoleTextFormatter()
provides span timings in a pleasant ANSI-colored format:
Log.Logger = new LoggerConfiguration()
// The `Formatters` class is from `SerilogTracing.Expressions`
.WriteTo.Console(Formatters.CreateConsoleTextFormatter(TemplateTheme.Code))
.CreateLogger();
Alternatively, TracingNameResolver
can be used with ExpressionTemplate
to create text or JSON output. The
example above expands into the (admittedly quite dense) template below:
var formatter = new ExpressionTemplate(
"[{@t:HH:mm:ss} {@l:u3}] " +
"{#if IsRootSpan()}\u2514\u2500 {#else if IsSpan()}\u251c {#else if @sp is not null}\u2502 {#else}\u250A {#end}" +
"{@m}" +
"{#if IsSpan()} ({Milliseconds(Elapsed()):0.###} ms){#end}" +
"\n" +
"{@x}",
theme: TemplateTheme.Code,
nameResolver: new TracingNameResolver());
Log.Logger = new LoggerConfiguration()
.WriteTo.Console(formatter)
.CreateLogger();
For an example showing how to produce JSON with ExpressionTemplate
, see the implementation of ZipkinSink
in this repository,
and this article introducing Serilog.Expressions JSON support.
How an Activity
becomes a LogEvent
Applications using SerilogTracing add tracing using ILogger.StartActivity()
. These activities are always converted into LogEvent
s and emitted through the original ILogger
that created them.
.NET libraries and frameworks add tracing using System.Diagnostics.ActivitySource
s. These activities are also emitted as LogEvent
s when using SerilogTracing.ActivityListenerConfiguration
.
Mapping trace concepts to event properties
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"] |
Kind | Properties["SpanKind"] |
Name | MessageTemplate |
Start | Properties["SpanStartTimestamp"] |
End | Timestamp |
Status | Level |
Status description or error event | Exception |
Tags | Properties[*] |
Levelling for external activity sources
SerilogTracing can consume activities from .NET itself, and libraries that don't themselves use SerilogTracing. By default, you'll see spans for all activities, from all sources, in your Serilog output.
To "turn down" the level of tracing performed by an external activity source, use SerilogTracing's InitialLevel
configuration to set a level for spans from that source:
.InitialLevel.Override("Npgsql", LogEventLevel.Debug)
In this example, when activities from the Npgsql activity source are assigned an initial level of Debug
, they'll be suppressed unless your Serilog logger has debug logging enabled.
Why is this an initial level?
The initial level assigned to a source determines whether activities are created by the source. When the activity is completed, it may be recorded at a higher level; for example, a span created at an initial Information
level may complete as an Error
(but not at a lower level such as Debug
, because doing so may suppress the span cause the trace hierarchy to become incoherent).
Recording Activity.Events
Activities produced by external .NET libraries may include one or more embedded ActivityEvent
s. By default, SerilogTracing
ignores these, except in the case of exception
events, which map to the LogEvent.Exception
property.
To emit additional LogEvent
s for each embedded ActivityEvent
, call ActivityEvents.AsLogEvents()
on ActivityListenerConfiguration
.
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.
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 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. |
.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. |
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.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.Instrumentation.SqlClient
Package Description |
|
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.1.1-dev-00324 | 130 | 7/29/2024 |
2.1.0 | 8,011 | 7/29/2024 |
2.1.0-dev-00322 | 63 | 7/29/2024 |
2.1.0-dev-00321 | 52 | 7/29/2024 |
2.1.0-dev-00320 | 61 | 7/29/2024 |
2.1.0-dev-00319 | 61 | 7/29/2024 |
2.1.0-dev-00317 | 101 | 7/24/2024 |
2.1.0-dev-00313 | 182 | 7/22/2024 |
2.0.1-dev-00312 | 126 | 7/22/2024 |
2.0.0 | 54,850 | 6/4/2024 |
2.0.0-dev-00306 | 154 | 6/3/2024 |
2.0.0-dev-00305 | 178 | 6/3/2024 |
2.0.0-dev-00304 | 165 | 6/1/2024 |
2.0.0-dev-00303 | 172 | 6/1/2024 |
1.1.0 | 24,309 | 5/2/2024 |
1.1.0-dev-00298 | 148 | 5/24/2024 |
1.1.0-dev-00297 | 150 | 5/24/2024 |
1.1.0-dev-00296 | 154 | 5/24/2024 |
1.1.0-dev-00295 | 119 | 5/16/2024 |
1.1.0-dev-00292 | 181 | 5/10/2024 |
1.1.0-dev-00287 | 188 | 5/1/2024 |
1.1.0-dev-00286 | 185 | 5/1/2024 |
1.1.0-dev-00283 | 171 | 4/30/2024 |
1.1.0-dev-00282 | 178 | 4/30/2024 |
1.0.1 | 11,899 | 4/18/2024 |
1.0.1-dev-00280 | 179 | 4/30/2024 |
1.0.1-dev-00276 | 146 | 4/18/2024 |
1.0.1-dev-00275 | 152 | 4/18/2024 |
1.0.1-dev-00273 | 15,015 | 3/26/2024 |
1.0.1-dev-00267 | 40,453 | 3/11/2024 |
1.0.1-dev-00266 | 271 | 3/11/2024 |
1.0.1-dev-00264 | 189 | 3/10/2024 |
1.0.1-dev-00261 | 835 | 3/5/2024 |
1.0.0 | 18,937 | 3/3/2024 |
1.0.0-dev-00257 | 2,963 | 2/29/2024 |
1.0.0-dev-00256 | 156 | 2/29/2024 |
1.0.0-dev-00251 | 807 | 2/27/2024 |
1.0.0-dev-00249 | 152 | 2/26/2024 |
1.0.0-dev-00247 | 166 | 2/26/2024 |
1.0.0-dev-00246 | 160 | 2/24/2024 |
1.0.0-dev-00242 | 1,259 | 2/22/2024 |
1.0.0-dev-00240 | 166 | 2/21/2024 |
1.0.0-dev-00236 | 163 | 2/21/2024 |
1.0.0-dev-00233 | 1,859 | 2/12/2024 |
1.0.0-dev-00231 | 489 | 2/12/2024 |
1.0.0-dev-00229 | 134 | 2/12/2024 |
1.0.0-dev-00228 | 162 | 2/12/2024 |
1.0.0-dev-00227 | 152 | 2/12/2024 |
1.0.0-dev-00225 | 150 | 2/12/2024 |
1.0.0-dev-00214 | 578 | 2/10/2024 |
1.0.0-dev-00179 | 156 | 2/9/2024 |
1.0.0-dev-00167 | 122 | 2/8/2024 |
1.0.0-dev-00164 | 153 | 2/8/2024 |
1.0.0-dev-00159 | 137 | 2/8/2024 |
1.0.0-dev-00155 | 165 | 2/7/2024 |
1.0.0-dev-00150 | 121 | 2/7/2024 |
1.0.0-dev-00142 | 234 | 2/6/2024 |
1.0.0-dev-00138 | 148 | 2/6/2024 |
1.0.0-dev-00135 | 155 | 2/6/2024 |
1.0.0-dev-00134 | 142 | 2/6/2024 |
1.0.0-dev-00132 | 191 | 2/5/2024 |
1.0.0-dev-00127 | 136 | 2/5/2024 |
1.0.0-dev-00121 | 176 | 2/1/2024 |
1.0.0-dev-00118 | 147 | 2/1/2024 |
1.0.0-dev-00115 | 147 | 2/1/2024 |
1.0.0-dev-00113 | 156 | 2/1/2024 |
1.0.0-dev-00107 | 124 | 1/31/2024 |
1.0.0-dev-00103 | 169 | 1/30/2024 |
1.0.0-dev-00102 | 1,056 | 1/25/2024 |
1.0.0-dev-00100 | 327 | 1/24/2024 |
1.0.0-dev-00097 | 142 | 1/24/2024 |
1.0.0-dev-00090 | 299 | 1/24/2024 |
1.0.0-dev-00088 | 1,002 | 1/22/2024 |
1.0.0-dev-00087 | 148 | 1/19/2024 |
1.0.0-dev-00086 | 105 | 1/18/2024 |
1.0.0-dev-00082 | 115 | 1/17/2024 |
1.0.0-dev-00080 | 116 | 1/17/2024 |
1.0.0-dev-00079 | 116 | 1/17/2024 |
1.0.0-dev-00077 | 111 | 1/17/2024 |
1.0.0-dev-00076 | 118 | 1/17/2024 |
1.0.0-dev-00070 | 110 | 1/16/2024 |
1.0.0-dev-00067 | 124 | 1/16/2024 |
1.0.0-dev-00066 | 111 | 1/16/2024 |
1.0.0-dev-00055 | 228 | 1/11/2024 |
1.0.0-dev-00051 | 100 | 1/10/2024 |
1.0.0-dev-00049 | 94 | 1/9/2024 |
1.0.0-dev-00044 | 95 | 1/9/2024 |
1.0.0-dev-00039 | 156 | 1/4/2024 |
1.0.0-dev-00038 | 82 | 1/4/2024 |
1.0.0-dev-00037 | 91 | 1/3/2024 |
1.0.0-dev-00034 | 81 | 1/3/2024 |
1.0.0-dev-00031 | 83 | 1/2/2024 |
1.0.0-dev-00030 | 95 | 1/2/2024 |
1.0.0-dev-00022 | 597 | 12/4/2023 |
1.0.0-dev-00017 | 103 | 11/28/2023 |
1.0.0-dev-00016 | 144 | 11/15/2023 |
1.0.0-dev-00015 | 89 | 11/15/2023 |
1.0.0-dev-00011 | 96 | 11/10/2023 |
1.0.0-dev-00010 | 586 | 11/7/2023 |
1.0.0-dev-00009 | 77 | 11/5/2023 |