C#/.NET Manual Instrumentation with OpenTracing

Want to use OpenTelemetry instead? Read these docs to get started!

Follow these steps to configure your tracer to communicate with the Cloud Observability Microsatellites and create a single span on your service. You install both the OpenTracing API and Cloud Observability tracer and then use the OpenTracing and Cloud Observability APIs to instrument your code.

While Cloud Observability offers tracers and APIs specific to its tracing software, you will still use the OpenTracing API to fully instrument your code. Be sure you have read and are familiar with the OpenTracing specification in your application’s language.

C# Instrumentation for OpenTracing

  1. Find your access token in Cloud Observability . You’ll need this to configure your Cloud Observability tracer.
    • Click the Project Settings button.
    • In the Access Tokens table, click the Copy icon to copy your access token to the clipboard.

  2. Add the Cloud Observability tracer to your .NET project using NuGet or by running the following command for .NET Core projects.

    1

    dotnet add package LightStep

  3. In your application code, add a reference to the Lightstep tracer and OpenTracing API.

    1
2

    using LightStep;
using OpenTracing.Util;

  4. Early in your application’s initialization, configure the Lightstep tracer and register it as the OpenTracing Global Tracer. As part of the configuration, you need to add your access token and add a tag for your service’s name. Use this table for Microsatellite options.

    Start tabs

    On-Premise Microsatellites

    1
2
3
4
5
6
7
8
9
10
11

     var satelliteOptions = new SatelliteOptions("your_load_balancer_DNS_name_or_IP_address");
 var overrideTags = new Dictionary<string, object>
 {
   { LightStepConstants.ComponentNameKey, "YOUR_SERVICE_NAME" },
   {"my_tag", "foobar"}
 };

 var tracerOptions = new Options("YOUR_ACCESS_TOKEN").WithSatellite(satelliteOptions).WithTags(overrideTags);
 var lightStepTracer = new Tracer(tracerOptions);

 GlobalTracer.Register(lightStepTracer);

    Public Microsatellites

    1
2
3
4
5
6
7
8
9
10
11

     var satelliteOptions = new SatelliteOptions("ingest.lightstep.com");
 var overrideTags = new Dictionary<string, object>
 {
   { LightStepConstants.ComponentNameKey, "YOUR_SERVICE_NAME" },
   {"my_tag", "foobar"}
 };

 var tracerOptions = new Options("YOUR_ACCESS_TOKEN").WithSatellite(satelliteOptions).WithTags(overrideTags);
 var lightStepTracer = new Tracer(tracerOptions);

 GlobalTracer.Register(lightStepTracer);

    Developer Mode

    1
2
3
4
5
6
7
8
9
10
11

     var satelliteOptions = new SatelliteOptions("localhost");
 var overrideTags = new Dictionary<string, object>
 {
   { LightStepConstants.ComponentNameKey, "YOUR_SERVICE_NAME" },
   {"my_tag", "foobar"}
 };

 var tracerOptions = new Options("YOUR_ACCESS_TOKEN").WithSatellite(satelliteOptions).WithTags(overrideTags);
 var lightStepTracer = new Tracer(tracerOptions);

 GlobalTracer.Register(lightStepTracer);

    End code tabs

  5. Test that everything is connected by sending a test span. Annotate the span by adding a tag (key/value pair) and logs, then flush the tracer.

    1
2
3
4
5
6
7
8
9
10

     var span = lightStepTracer.BuildSpan("testSpan").Start();
 span.Log("This is a log message!");
 // for tag value, use either "client" or "server" depending on whether
 // this service receives or creates requests
 span.SetTag("span.kind", "client");
 span.Finish();
 // manually flush the tracer to make sure your span is sent.
 lightStepTracer.Flush();

 // if this is a console app, make sure you Console.ReadKey() or have some other sort of blocking behavior as flushing the tracer is asynchronous.
  6. Run your app.
  7. Open Cloud Observability . You should see your service in the Service directory list.

If you want to continue adding instrumentation by creating more spans and connecting them into traces, read the OpenTracing C# README on GitHub.

It may take a few moments for your service to display in the Service Directory. To see data immediately, click the Explorer tab to view data in the histogram.

See also

Updated Mar 2, 2020