Setup and Install OpenTelemetry .NET C#

Get up and running with OpenTelemetry in just a few quick steps! The setup process consists of two phases--getting OpenTelemetry installed and configured, and then validating that configuration to ensure that data is being sent as expected.

OpenTelemetry automatically captures telemetry from your application's libraries, frameworks, and environment. This guide explains how to install, configure, and validate your OpenTelemetry setup.

Requirements

  • OpenTelemetry for .NET supports .NET Framework 4.6.2+ or .NET Core 2.1+
  • A service to add OpenTelemetry to. You can use this example application or bring your own.
  • A Lightstep account, or another OpenTelemetry backend.

Need an account? Create a free Lightstep account here.

Installation

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:

dotnet add package OpenTelemetry --version 0.8.0-beta.1
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol -v 0.8.0-beta.1

Run OpenTelemetry

To set up OpenTelemetry in your application, you need to create a TracerProvider. The example below creates a TracerProvider configured via environment variables.

Your Access Token can be found in your project settings page.

Environment Variables

  • LS_ACCESS_TOKEN is required when connecting to Lightstep. .
  • LS_SERVICE_NAME the name of your service as it will appear in Lightstep.
  • LS_SERVICE_VERSION is not required but very much recommended.
using System;
using Grpc.Core;
using System.Diagnostics;
using OpenTelemetry;
using OpenTelemetry.Trace;
using OpenTelemetry.Resources;

class Program
    {
        private static readonly ActivitySource MyActivitySource = new ActivitySource("MyCompany.MyProduct.MyLibrary");

        static void Main(string[] args)
        {
            using var openTelemetry = Sdk.CreateTracerProviderBuilder()
                    .AddSource("MyCompany.MyProduct.MyLibrary")
                    .SetResource(Resources.CreateServiceResource(Environment.GetEnvironmentVariable("LS_SERVICE_NAME"), serviceVersion: Environment.GetEnvironmentVariable("LS_SERVICE_VERSION")))
                    .AddOtlpExporter(opt => {
                        opt.Endpoint = "ingest.lightstep.com:443";
                        opt.Headers = new Metadata
                        {
                            { "lightstep-access-token", Environment.GetEnvironmentVariable("LS_ACCESS_TOKEN")}
                        };
                        opt.Credentials = new SslCredentials();
                    })
                    .Build();

        using (var activity = MyActivitySource.StartActivity("SayHello"))
        {
            activity?.SetTag("foo", 1);
            activity?.SetTag("bar", "Hello, World!");
            activity?.SetTag("baz", new int[] { 1, 2, 3 });
        }
    }

As a reminder, Lightstep requires the service.name resource to be set, either by configuring a resource as shown above, or by setting the ServiceName field on a OtlpExporter -- an example of this is below, that you could use for configuring automatic instrumentation of an ASP.NET Core application:

public void ConfigureServices(IServiceCollection services)
{
  // add to your existing service collection
  services.AddOpenTelemetryTracing((builder) => builder
    .AddAspNetCoreInstrumentation()
    .AddHttpClientInstrumentation()
    .AddOtlpExporter(otlpOptions =>
      {
        otlpOptions.ServiceName = Environment.GetEnvironmentVariable("LS_SERVICE_NAME");
        otlpOptions.Endpoint = "ingest.lightstep.com:443";
        otlpOptions.Headers = new Metadata
          {
            { "lightstep-access-token", Environment.GetEnvironmentVariable("LS_ACCESS_TOKEN")}
          };
         otlpOptions.Credentials = new SslCredentials();
      }));
}

Auto-Instrumentation

The following libraries are currently supported by OpenTelemetry. Visit the READMEs for installation instructions.

Validate Installation by Checking for Traces

With your application running, you can now verify that you’ve installed OpenTelemetry correctly by confirming that telemetry data is being reported to your observability backend.

To do this, you need to make sure that your application is actually generating data. Applications will generally not produce traces unless they are being interacted with, and opentelemetry will often buffer data before sending it. So it may take some amount of time and interaction before your application data begins to appear in your backend.

Validate your traces in Lightstep:

  1. Trigger an action in your app that generates a web request.
  2. In Lightstep, click on the Explorer in the sidebar.
  3. Refresh your query until you see traces.
  4. View the traces and verify that important aspects of your application are captured by the trace data.