SerilogTracing 1.0.0-dev-00022

SerilogTracing

⚠ This project isn't ready to check out just yet, please drop by again soon.

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 using the .NET APIs through Serilog sinks, and
2. Generate rich traces using Serilog APIs and idioms, that can still be observed by other consumers of the .NET APIs.

There are two main scenarios where these capabilities combine usefully.

First, at 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:

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!

Second, 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:

![]

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

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 ParentSpanId and SpanStartTimestamp properties to represent the parts of a span not already covered by the other parts of the LogEvent.

SerilogTracing needs to hook into the logging pipeline at creation time; currently this must be done using:

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

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

TBA.

Configuring the activity listener

TBA. Need a discussion of how sources can be filtered or ignored using MinimumLevel.Override on the target logger.

Formatting spans with ExpressionTemplate

TBA.

Status and known limitations

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

Other limitations generally stem from the project's immaturity or implementation state: if something listed here interests you, feel free to hack away on a fork and propose any useful changes you can come up with!

• Not much thought has been given to sampling.
• Non-W3C id formats haven't been considered at all.
• Activities generated by SerilogTracing won't expose source names based on ForContext<T>() to other ActivityListeners, instead marking the activities as from the generic Serilog.Core.Logger source. To expose richer source names, use the generic overload of the StartActivity extension method.
• Serilog.Sinks.OpenTelemetry, which should be a useful output for SerilogTracing, doesn't yet include any support for emitting spans over OTLP.
• No generic mechanism has been considered nor implemented for suppressing instrumentation during operations, e.g. sinks may themselves trigger creation of new spans, if steps aren't taken to prevent it.
• Activity baggage is ignored.
• Activity properties are ignored, no enrichment of generated spans from non-tag activity information has been implemented.
• Because the API hooks logger creation, it doesn't currently sit well alongside CreateBootstrapLogger.