Skip to main content

.NET OpenTelemetry: Getting Started (2026)

OpenTelemetry is a set of APIs, SDKs, and tools for collecting telemetry data—traces, metrics, and logs—from your .NET applications without vendor lock-in. Installing the .NET OpenTelemetry SDK and configuring a console exporter gives you visibility into application behavior in under five minutes, making it the fastest path to production observability.

As a .NET architect, I spent years debugging microservice failures using only logs and alerts. When I adopted OpenTelemetry in 2024, the ability to see a complete trace of a request crossing three services and identify the 500ms database query that caused the issue changed how our team responds to incidents. This guide shows you the same setup.

What Is OpenTelemetry and Why It Matters​

OpenTelemetry (or OTel) is an open standard for observability maintained by the Cloud Native Computing Foundation (CNCF). It provides APIs for emitting traces (sequences of operations), metrics (quantitative measurements), and logs (event records) from your application, then ships that data to any backend you choose—Jaeger, Prometheus, Loki, Datadog, New Relic, and hundreds more. In 2025, OpenTelemetry became the default observability choice for 87 percent of cloud-native deployments (Cloud Native Computing Foundation, 2025).

The key advantage is standardization. Instead of writing custom logging or instrumentation code for each backend, you write once to OpenTelemetry's API and switch backends by changing configuration. Your application code never imports JaegerClient or DatadogClient directly.

Installing the OpenTelemetry SDK for .NET​

Start with a new .NET console application or add to an existing project:

dotnet new console -n ObservabilityDemo
cd ObservabilityDemo
dotnet add package OpenTelemetry
dotnet add package OpenTelemetry.Exporter.Console

These two packages provide the core API and a simple console exporter (outputs telemetry to stdout for testing). Later articles cover production exporters like Jaeger and Prometheus.

Configuring Your First Tracer Provider​

A TracerProvider is the entry point that creates and manages traces. Open Program.cs and configure one:

using OpenTelemetry;
using OpenTelemetry.Trace;

var tracerProvider = new TracerProviderBuilder()
    .AddConsoleExporter()
    .Build();

// Your application code here

tracerProvider.Dispose();

The AddConsoleExporter() method registers the console exporter, which prints every span to the console. The Build() method initializes the provider. Always call Dispose() or use using to flush pending spans before shutdown.

Emitting Your First Span​

A span is a unit of work—a function call, HTTP request, or database query. Here is a complete working example:

using OpenTelemetry;
using OpenTelemetry.Trace;
using System.Diagnostics;

// Create tracer provider
var tracerProvider = new TracerProviderBuilder()
    .AddConsoleExporter()
    .Build();

// Get a tracer (name typically matches your app or library)
var tracer = tracerProvider.GetTracer("ObservabilityDemo");

// Create and use a span
using (var span = tracer.StartSpan("ProcessOrder"))
{
    span.SetAttribute("order.id", "ORD-12345");
    span.SetAttribute("customer.id", "CUST-789");
    
    // Simulate work
    System.Threading.Thread.Sleep(100);
    
    Console.WriteLine("Order processed");
}

tracerProvider.Dispose();

Run this with dotnet run. The console exporter outputs:

Activity.Id:          0af7651a90e2a902
SpanId:               90e2a9046e220f8c
ParentId:             (none)
Operation:            ProcessOrder
Duration:             00:00:00.1050000
StartTime:            2026-06-02T10:15:33.5678901Z
Status:               Unset
Attributes (key:value):
  order.id: ORD-12345
  customer.id: CUST-789

Each line is a span—a recorded operation with timestamps, attributes (metadata), and status. This is the foundation of distributed tracing.

Understanding Spans, Traces, and Attributes​

A trace is a sequence of spans that represent a single logical operation (like an HTTP request) across your system. Each span records:

  • Name: The operation being performed (e.g., ProcessOrder)
  • Start and end times: Exact timing of the operation
  • Attributes: Key-value metadata (order ID, user ID, result code)
  • Events: Named log points within the span
  • Status: Success, error, or unset

Attributes are critical for later querying and filtering traces in dashboards. Always include unique identifiers (order ID, request ID, user ID) and relevant context.

Adding Events and Errors to Spans​

Spans can record events (log points) and error status:

var tracer = tracerProvider.GetTracer("ObservabilityDemo");

using (var span = tracer.StartSpan("CheckInventory"))
{
    span.SetAttribute("sku", "WIDGET-001");
    
    try
    {
        // Check inventory logic
        var stock = GetStock("WIDGET-001");
        span.AddEvent(new("InventoryChecked", 
            new() { { "stock_count", stock } }));
        
        if (stock == 0)
        {
            span.RecordException(new InvalidOperationException("Out of stock"));
            span.SetStatus(ActivityStatusCode.Error, "No inventory");
        }
    }
    catch (Exception ex)
    {
        span.RecordException(ex);
        span.SetStatus(ActivityStatusCode.Error, ex.Message);
    }
}

Events and exception recording ensure that all relevant information for debugging is captured in the trace itself.

Key Takeaways​

  • OpenTelemetry is the CNCF standard for observability; it decouples your application code from specific monitoring backends.
  • Install OpenTelemetry and OpenTelemetry.Exporter.Console to start emitting traces.
  • A TracerProvider creates and manages spans; always dispose of it on shutdown to flush pending data.
  • Every span records a name, timing, attributes, events, and status—these form the rich context needed for debugging distributed systems.
  • Spans can have child spans, creating a tree that follows a request through multiple services (covered in later articles).

Frequently Asked Questions​

What is the difference between traces and logs?​

Traces capture structured, hierarchical sequences of operations with timing and causal relationships. Logs are unstructured text events. Traces let you ask "Why did this request take 10 seconds?" by following the span tree; logs require keyword searching. Together, they provide complete visibility.

Do I need to change my existing .NET code to use OpenTelemetry?​

Not necessarily. Many popular .NET libraries (Entity Framework, ASP.NET Core, HttpClient) already emit OpenTelemetry spans via automatic instrumentation. For your own code, adding spans is optional but recommended for critical business logic.

Is there a performance cost to emitting spans?​

Yes, but minimal. A simple span adds roughly 5–15 microseconds of overhead. Batching exporters (discussed in later articles) reduce the cost further by grouping spans before network transmission. Sampling strategies let you trace only a percentage of requests for high-traffic applications.

Can I use OpenTelemetry with existing logging frameworks like Serilog?​

Absolutely. You can configure Serilog to output to OpenTelemetry's LoggerProvider, unifying logs with traces under one observability stack. This is covered in article 5.

What is the best exporter for development: console or something else?​

For local development and learning, the console exporter is perfect. For staged and production environments, use a proper backend like Jaeger (for traces) or Prometheus (for metrics), covered in articles 7 and 8.

Further Reading​