trace and baggage context across network boundaries so that different services in your system can participate in the same trace.
The W3C provides standards for propagation:
These contexts are transferred in HTTP headers (or other protocols), typically as traceparent for trace context and baggage for baggage context. Below, we will explore how this works in .NET with OpenTelemetry.
The traceparent header contains information about the current trace.
traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
Format
A trace (or span) is represented by an Activity object. Each Activity instance corresponds to one span in the trace.
The baggage header holds additional context in the form of key=value pairs.
baggage: key1=value1
Do not use Activity.Baggage to read or modify baggage. Instead, use Baggage.Current from the OpenTelemetry.Api package.
This ensures that baggage context is managed consistently with the OpenTelemetry specifications.
Important: These header values are transferred in plaintext to outgoing HTTP requests — internal, third parties, etc. Avoid placing sensitive or personally identifiable information in the baggage context.
Tracing configuration registers TraceContextPropagator and BaggageContextPropagator out of the box.
builder.Services.AddOpenTelemetry()
.UseOtlpExporter()
.ConfigureResource(configure => {
configure.AddService(builder.Environment.ApplicationName)
})
.WithTracing();
These propagators enable extracting traceparent and baggage headers format from incoming requests and injecting them into outgoing requests.
If you need support for alternative or custom propagators (e.g., Zipkin headers), you can set them explicitly using a CompositeTextMapPropagator
Sdk.SetDefaultTextMapPropagator(new CompositeTextMapPropagator(
new List<TextMapPropagator>() {
new MyCustomPropagator()
}));
By adding the following instrumentation, OpenTelemetry will automatically handle context propagation for incoming and outgoing HTTP requests.
builder.Services.AddOpenTelemetry()
.UseOtlpExporter()
.ConfigureResource(configure => {
configure.AddService(builder.Environment.ApplicationName)
})
.WithTracing(tracing =>
{
tracing
.AddAspNetCoreInstrumentation()
.AddHttpClientInstrumentation();
});
If you want to see how this works under the hood, check out the OpenTelemetry .NET code for incoming HTTP instrumentation and outgoing HTTP instrumentation.
For protocols not natively instrumented (messaging systems, outbox, etc), you’ll need to manually propagate the context by calling the Inject and Extract methods on the Propagators.DefaultTextMapPropagator.
public void SendMessage(IMessage message)
{
var propagationContext = new PropagationContext(Activity.Current?.Context ?? default, Baggage.Current);
Propagators.DefaultTextMapPropagator.Inject(
propagationContext,
message.Headers,
(headers, key, value) => headers[key] = value
);
// Publishing ...
}
public void ProcessMessage(IMessage message)
{
var propagationContext = Propagators.DefaultTextMapPropagator.Extract(
default,
message.Headers,
(headers, key) => headers.TryGetValue(key, out var value) ? new[] { value } : Array.Empty<string>()
);
using var activity = ActivityProvider.ActivitySource.StartActivity("receive", ActivityKind.Consumer, propagationContext.ActivityContext);
Baggage.Current = propagationContext.Baggage;
// Processing ...
}
Using this approach, you maintain consistent trace and baggage context across any protocol or communication mechanism in your distributed system.
The .NET runtime contains most of Metric API, that allows applications to emit OpenTelemetry metrics using the standard .NET runtime.
Use the Meter class, which is responsible for creating metric instruments to create manual metrics from the System.Diagnostics.DiagnosticSource nuget package.
static readonly Meter meter = new("serviceName", "1.0");
The default, there is no listener to meters; they need to be explicit configured into the MeterProvider. The MeterProvider is the entry point to the configuration of all Meter’s and their instrumentation.
It’s not recommended to initialize the instrument for every metric execution. Create a (static) wrapper over metrics.
Initialize some kinds of instruments - Counter, Gauge, Histogram, …
public static class ApplicationMetrics
{
private static readonly Meter meter = new Meter("applicationName", "1.0.0");
private static readonly Counter<int> applicationCounter = meter.CreateCounter<int>("applicationCounter");
public static void IncreaceCounter() => applicationCounter.Add(1);
}
public void SomeMethod()
{
// Code
ApplicationMetrics.IncreaceCounter();
// Code
}
It provides a way to aggregate large number of measurements. More detailed description here.
It provides a way to customize the metrics output - which metric instruments are to be processed, which attributes report. More detailed description here.
As tracing, also metrics are part of the OpenTelemetry.Extensions.Hosting nuget package.
builder.Services.AddOpenTelemetry()
.WithMetrics(metrics =>
{
metrics.SetResourceBuilder(ResourceBuilder.CreateDefault()
.AddService("serviceName"))
.AddMeter("serviceName"); // Configure meter to listen
});
Metrics instruments must be registered by AddMeter("meterName") to MeterProvider. There exist some build-in Meter’s to instrument ASP.NET application
Microsoft.AspNetCore.Hosting, Microsoft.AspNetCore.Server.Kestrel, System.Net.Http.
To instrument the application’s runtime (ram, cpu, gc,…) install OpenTelemetry.Instrumentation.Runtime and configure it by AddRuntimeInstrumentation.
builder.Services.AddOpenTelemetry()
.WithMetrics(metrics =>
{
metrics.SetResourceBuilder(ResourceBuilder.CreateDefault()
.AddService("serviceName"))
.AddMeter("serviceName"); // Configure meter to listen
.AddMeter("Microsoft.AspNetCore.Hosting", "Microsoft.AspNetCore.Server.Kestrel", "System.Net.Http");
.AddRuntimeInstrumentation()
});
There are several ways to export metrics to backends - OTLP, Console, and Prometheus in the namespace of the OpenTelemetry.Exporter.NAME nuget package.
To enable OTLP exporter for all signals, there is exists an extension UseOtlpExporter.
builder.Services.AddOpenTelemetry()
.UseOtlpExporter();
The .NET runtime contains an Activity class, which is used for tracing purposes and represents a Span in OpenTelemetry terminology. The Activity class is part of the System.Diagnostics.DiagnosticSource package.
This allows applications to emit OpenTelemetry traces using the standard .NET Runtime.
To align more closely with OpenTelemetry terminology (like tracer, span instead of activitySource, activity) in the application, use the OpenTelementry.API, which wraps the .NET Activity classes.
Use the ActivitySource class, which provides the name and version of the application doing the instrumentation. The instance of ActivitySource should be created once and reused throughout the application.
static ActivitySource activitySource = new ActivitySource(
"serviceName",
"1.0.0");
Use the ActivitySource instance to create an Activity instance, which represents a single-span operation.
using var activity = activitySource.StartActivity("ActivityName");
If there are no listeners/samplers interested in this activity, the StartActivity returns null.
The StartActivity method starts an activity and sets it as the current activity in the ActivityContext.Current and propagates the ActivityContext from the parent activity.
using var activity = activitySource.StartActivity("ActivityName");
activity?.SetTag("http.url", "url");
activity?.AddEvent(new ActivityEvent("activity event"));
activity?.SetStatus(ActivityStatusCode.Error, "error");
Populate activity with tags follow the OpenTelemetry semantic conventions.
Install the nuget package OpenTelemetry.Extensions.Hosting to expose the OpenTelemetry SDK.
builder.Services.AddOpenTelemetry()
.WithTracing(tracing =>
{
tracing.SetResourceBuilder(ResourceBuilder.CreateDefault()
.AddService("serviceName"))
.AddSource("serviceName"); // Configure sources to listen
});
There are two ways how to instrument.
Activity class.OpenTelemetry.AutoInstrumentation nuget package.Automatic instrumentation can also enabled by OpenTelemetry.Instrumentation.X nuget packages that are specific per resource.
For example, instruments for HTTP Requests (In) and Requests (Out) are in the OpenTelemetry.Instrumentation.AspNetCore and OpenTelemetry.Instrumentation.Http packages, which also configures and propagates trace context through Propagator API via HTTP Headers.
builder.Services.AddOpenTelemetry()
.WithTracing(tracing =>
{
tracing.SetResourceBuilder(ResourceBuilder.CreateDefault()
.AddService("serviceName"))
.AddSource("serviceName"); // Configures sources to listen (instrument)
.AddAspNetCoreInstrumentation() // HTTP Requests (In) - Configures tracing context from headers
.AddHttpClientInstrumentation() // HTTP Requests (Out) - Propagates tracing context to headers
});
Sampling (especially Head Sampling) can be configured by tracing.SetSampler(...).
Exporters allow an application to send instrumentation data to various backends, such as Console, Zipkin, or OTLP.
For example, export traces to the OTLP collector by OpenTelemetry.Exporter.OpenTelemetryProtocol and configure it using OTLP Exporter Configuration.
builder.Services.AddOpenTelemetry()
.WithTracing(tracing =>
{
tracing.SetResourceBuilder(ResourceBuilder.CreateDefault()
.AddService("serviceName"))
.AddSource("serviceName"); // Configure sources to listen (instrument)
.AddAspNetCoreInstrumentation() // HTTP Requests (In)
.AddHttpClientInstrumentation() // HTTP Requests (Out)
.AddOtlpExporter()
});