This Quick Start shows you how to use OpenTelemetry in your .NET app to:

  • Configure a tracer
  • Generate trace data
  • Propagate context over HTTP
  • Export the trace data to the console and to Lightstep

This Quick Start uses a simple app to show how to propagate context over HTTP.

Requirements

The OpenTelemetry .NET API supports .NET Framework 4.6+ and .NET Standard 2.0.

Setup

To get started with OpenTelemetry, you need to install both the API and SDK packages. These can either be installed using an IDE or by command line like below:

1
2
3
4
5
6
dotnet add package OpenTelemetry -v "0.2.0-*" -s
https://www.myget.org/F/opentelemetry/api/v3/index.json

dotnet add package OpenTelemetry.Exporter.Console -v "0.2.0-*" -s
https://www.myget.org/F/opentelemetry/api/v3/index.json

The Console exporter has not yet been published to nuget.org. This topic uses a pre-release version created during nightly CI that’s published to MyGet.

Collect Trace Data

You need to configure a TraceProvider to collect tracing information. A tracer is an object that tracks the currently active span and allows you to create (or activate) new spans. As spans are created and completed, the tracer dispatches them to an exporter that can send the spans to a backend system for analysis.

In this first example, the tracer is configured to use ConsoleExporter, which prints tracing information to the console.

  1. Use OpenTelemetry to create a tracer configured to send data to the console.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    
    using System;
    using OpenTelemetry.Trace;
    using OpenTelemetry.Trace.Configuration;
    
    // create exporter options
    var exporterOptions =
      new OpenTelemetry.Exporter.Console.ConsoleExporterOptions
      {
        Pretty = true
      };
    
    // create exporter
    var exporter =
      new OpenTelemetry.Exporter.Console.ConsoleExporter(exporterOptions);
    
    // Create tracer factory
    var tracerFactory = TracerFactory.Create(builder => {
      builder.AddProcessorPipeline(p => p.SetExporter(exporter));
    });
    
    // Get tracer
    var tracer = tracerFactory.GetTracer("my-tracer");
    
  2. Now that you have a tracer, create a span and add some attributes to it to make it more interesting.

    1
    2
    3
    
    tracer.StartActiveSpan("parent-span", out var span);
    tracer.CurrentSpan.SetAttribute("platform", "osx");
    tracer.CurrentSpan.SetAttribute("version", "1.2.3");
    
  3. Create relationships between spans in a parent child form by passing in the parent span to the function that creates the next span.

    1
    2
    
    tracer.StartActiveSpan("parent-span", out var parent);
    tracer.StartActiveSpan("child-span", parent, out var child);
    
  4. End the spans by marking them as complete, which allows them to be sent to a registered exporter.

    1
    2
    3
    4
    5
    6
    
    tracer.StartActiveSpan("my-span", out var span);
    tracer.CurrentSpan.SetAttribute("platform", "osx");
    tracer.CurrentSpan.End();
    
    // wait for exporter to flush spans to the console
    Console.ReadKey();
    

Due to an open issue, the ConsoleExporter does not correctly serialize a span’s ParentSpanId property. This will be corrected in a future release.

Propagate the Context Over HTTP

Creating spans within the same process is useful, but tracing is really useful when deployed in an environment across multiple processes. In this step, you’ll propagate span context using HTTP headers in a client-server scenario between processes and maintain the relationships between spans.

  1. Configure OpenTelemetry to use the HTTP propagator by installing the HttpClient Collector package.

    1
    2
    
    dotnet add package OpenTelemetry.Collector.Dependencies -v "0.2.0-*" -s
    https://www.myget.org/F/opentelemetry/api/v3/index.json
    
  2. Configure the tracer factory to use the collector.

    1
    2
    3
    
     var tracerFactory = TracerFactory.Create(builder => {
       builder.AddCollector(t => new HttpClientCollector(t));
     });
    
  3. With the HttpCollector configured, the OpenTelemetry SDK automatically creates spans based on the application interacting with HttpClient. Make a HTTP request and see what happens.

    1
    2
    
    var client = new HttpClient();
    var result = client.GetAsync("http://test.com").Result;
    
  4. Run your project and wait a few seconds.
    The spans that are automatically created when sending the HTTP request are printed out to the Console.

Export and Explore Trace Data in Lightstep

You used the Console exporter, but trace data can be sent to many different systems which can build deep and interesting metrics and graphs using the telemetry data.

If you don’t already have a Lightstep account, you can create a free account here.

  1. To send span data to Lightstep, get the Lightstep exporter.

    1
    2
    
    dotnet add package OpenTelemetry.Exporter.LightStep -s
    https://www.myget.org/F/opentelemetry/api/v3/index.json -v 0.2.0-*
    
  2. Configure the exporter. Each exporter has different settings and requirements. For Lightstep, you need a Lightstep access token.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    
    // create exporter
    var exporter = new ConsoleExporter(new LightStepExporterOptions
    {
      AccessToken = "your-access-token",
      ServiceName = "your-service-name"
    });
    
    // Create tracerFactory
    var tracerFactory = TracerFactory.Create(builder => {
      builder.AddProcessorPipeline(p => p.SetExporter(exporter));
    });
    
    // Get tracer
    var tracer = tracerFactory.GetTracer("my-tracer")
    

Now when a span is finished it is sent to your Lightstep satellite where service diagrams and other system information can be extracted, analyzed, and viewed.