OpenTelemetry .NET SDK - distributed tracing and stats collection framework

.NET Channel:

Community Channel:

We hold regular meetings. See details at community page.

OpenTelemetry is a toolkit for collecting application performance and behavior data.

The library is in Alpha stage. The library is expected to move to GA stage after v1.0.0 major release.

Please join gitter for help or feedback on this project.

We encourage contributions. Use tags up-for-grabs and good first issue to get started with the project. Follow CONTRIBUTING guide to report issues or submit a proposal.

Packages

Nightly builds

Myget feeds:

• NuGet V3 feed: https://www.myget.org/F/opentelemetry/api/v3/index.json
• NuGet V2 feed: https://www.myget.org/F/opentelemetry/api/v2

API and implementation

Package	MyGet (CI)	NuGet (releases)
OpenTelemetry
OpenTelemetry.Abstractions

Data Collectors

Package	MyGet (CI)	NuGet (releases)
Asp.Net Core
.Net Core HttpClient & Azure SDKs
StackExchange.Redis

Exporters Packages

Package	MyGet (CI)	NuGet (releases)
Zipkin
Prometheus
Application Insights
Stackdriver

OpenTelemetry QuickStart: collecting data

You can use OpenTelemetry API to instrument code and report data. Or use one of automatic data collection modules.

Basic Configuration

1. Install packages to your project: OpenTelemetry OpenTelemetry.Exporter.Zipkin

2. Create exporter and tracer

    var zipkinExporter = new ZipkinTraceExporter(new ZipkinTraceExporterOptions());
    var tracer = new Tracer(new BatchingSpanProcessor(zipkinExporter), TraceConfig.Default);
   

Configuration with DependencyInjection

1. Install packages to your project: OpenTelemetry OpenTelemetry.Collector.AspNetCore to collect incoming HTTP requests OpenTelemetry.Collector.Dependencies to collect outgoing HTTP requests and Azure SDK calls

2. Make sure ITracer, ISampler, and SpanExporter and SpanProcessor are registered in DI.

   services.AddSingleton<ISampler>(Samplers.AlwaysSample);
   services.AddSingleton<ZipkinTraceExporterOptions>(_ => new ZipkinTraceExporterOptions { ServiceName = "my-service" });
   services.AddSingleton<SpanExporter, ZipkinTraceExporter>();
   services.AddSingleton<SpanProcessor, BatchingSpanProcessor>();
   services.AddSingleton<TraceConfig>();
   services.AddSingleton<ITracer, Tracer>();
   
   // you may also configure request and dependencies collectors
   services.AddSingleton<RequestsCollectorOptions>(new RequestsCollectorOptions());
   services.AddSingleton<RequestsCollector>();
   
   services.AddSingleton<DependenciesCollectorOptions>(new DependenciesCollectorOptions());
   services.AddSingleton<DependenciesCollector>();
   

3. Start auto-collectors

   To start collection, RequestsCollector and DependenciesCollector need to be resolved.

   public void Configure(IApplicationBuilder app, RequestsCollector requestsCollector,  DependenciesCollector dependenciesCollector)
   {
       // ...
   }
   

Using StackExchange.Redis collector

Outgoing http calls to Redis made using StackExchange.Redis library can be automatically tracked.

1. Install package to your project: OpenTelemetry.Collector.StackExchangeRedis

2. Make sure ITracer, ISampler, and SpanExporter and SpanProcessor are registered in DI.

   services.AddSingleton<ISampler>(Samplers.AlwaysSample);
   services.AddSingleton<ZipkinTraceExporterOptions>(_ => new ZipkinTraceExporterOptions { ServiceName = "my-service" });
   services.AddSingleton<SpanExporter, ZipkinTraceExporter>();
   services.AddSingleton<SpanProcessor, BatchingSpanProcessor>();
   services.AddSingleton<TraceConfig>();
   services.AddSingleton<ITracer, Tracer>();
   
   // configure redis collection
   services.AddSingleton<StackExchangeRedisCallsCollectorOptions>(new StackExchangeRedisCallsCollectorOptions());
   services.AddSingleton<StackExchangeRedisCallsCollector>();
   

3. Start auto-collectors

   To start collection, StackExchangeRedisCallsCollector needs to be resolved.

   public void Configure(IApplicationBuilder app, StackExchangeRedisCallsCollector redisCollector)
   {
       // ...
   }
   
   

OpenTelemetry QuickStart: exporting data

Using the Jaeger exporter

The Jaeger exporter communicates to a Jaeger Agent through the compact thrift protocol on the Compact Thrift API port. You can configure the Jaeger exporter by following the directions below:

1. Get Jaeger.
2. Configure the JaegerExporter
   • ServiceName: The name of your application or service.
   • AgengHost: Usually localhost since an agent should usually be running on the same machine as your application or service.
   • AgentPort: The compact thrift protocol port of the Jaeger Agent (default 6831)
   • MaxPacketSize: The maximum size of each UDP packet that gets sent to the agent. (default 65000)
3. See the sample for an example of how to use the exporter.

var exporter = new JaegerExporter(
    new JaegerExporterOptions
    {
        ServiceName = "tracing-to-jaeger-service",
        AgentHost = host,
        AgentPort = port,
    });

var tracer = new Tracer(new BatchingSpanProcessor(exporter), TraceConfig.Default);

var span = tracer
            .SpanBuilder("incoming request")
            .SetSampler(Samplers.AlwaysSample)
            .StartSpan();

await Task.Delay(1000);
span.End();

// Gracefully shutdown the exporter so it'll flush queued traces to Jaeger.
// you may need to catch `OperationCancelledException` here
await exporter.ShutdownAsync(CancellationToken.None);

Using Zipkin exporter

Configure Zipkin exporter to see traces in Zipkin UI.

1. Get Zipkin using getting started guide.
2. Start ZipkinTraceExporter as below:
3. See sample for example use.

var exporter = new ZipkinTraceExporter(
  new ZipkinTraceExporterOptions() {
    Endpoint = new Uri("https://<zipkin-server:9411>/api/v2/spans"),
    ServiceName = typeof(Program).Assembly.GetName().Name,
  });
var tracer = new Tracer(new BatchingSpanProcessor(exporter), TraceConfig.Default);

var span = tracer
            .SpanBuilder("incoming request")
            .SetSampler(Samplers.AlwaysSample)
            .StartSpan();

await Task.Delay(1000);
span.End();

// Gracefully shutdown the exporter so it'll flush queued traces to Jaeger.
// you may need to catch `OperationCancelledException` here
await exporter.ShutdownAsync(CancellationToken.None);

Using Prometheus exporter

Configure Prometheus exporter to have stats collected by Prometheus.

1. Get Prometheus using getting started guide.
2. Start PrometheusExporter as below.
3. See sample for example use.

var exporter = new PrometheusExporter(
    new PrometheusExporterOptions()
    {
        Url = "http://+:9184/metrics/"
    },
    Stats.ViewManager);

exporter.Start();

try
{
    // record metrics
    statsRecorder.NewMeasureMap().Put(VideoSize, values[0] * MiB).Record();
}
finally
{
    exporter.Stop();
}

Using Stackdriver Exporter

This sample assumes your code authenticates to Stackdriver APIs using service account with credentials stored in environment variable GOOGLE_APPLICATION_CREDENTIALS. When you run on GAE, GKE or locally with gcloud sdk installed - this is typically the case. There is also a constructor for specifying path to the service account credential. See sample for details.

1. Add Stackdriver Exporter package reference.
2. Enable Stackdriver Trace API.
3. Enable Stackdriver Monitoring API.
4. Instantiate a new instance of StackdriverExporter with your Google Cloud's ProjectId
5. See sample for example use.

Traces

var traceExporter = new StackdriverTraceExporter("YOUR-GOOGLE-PROJECT-ID");
var tracer = new Tracer(new BatchingSpanProcessor(exporter), TraceConfig.Default);

var span = tracer
            .SpanBuilder("incoming request")
            .SetSampler(Samplers.AlwaysSample)
            .StartSpan();

await Task.Delay(1000);
span.End();

// Gracefully shutdown the exporter so it'll flush queued traces to Jaeger.
// you may need to catch `OperationCancelledException` here
await exporter.ShutdownAsync(CancellationToken.None);

Metrics

var metricExporter = new StackdriverExporter(
    "YOUR-GOOGLE-PROJECT-ID",
    Stats.ViewManager);
metricExporter.Start();

Using Application Insights exporter

1. Create Application Insights resource.
2. Set instrumentation key via telemetry configuration object (new TelemetryConfiguration("iKey")). This object may be injected via dependency injection as well.
3. Instantiate a new instance of ApplicationInsightsExporter.
4. See sample for example use.

var config = new TelemetryConfiguration("iKey")
var exporter = new ApplicationInsightsExporter(config);
var tracer = new Tracer(new BatchingSpanProcessor(exporter), TraceConfig.Default);

var span = tracer
            .SpanBuilder("incoming request")
            .SetSampler(Samplers.AlwaysSample)
            .StartSpan();

await Task.Delay(1000);
span.End();

// Gracefully shutdown the exporter so it'll flush queued traces to Jaeger.
// you may need to catch `OperationCancelledException` here
await exporter.ShutdownAsync(CancellationToken.None);

Versioning

This library follows Semantic Versioning.

GA: Libraries defined at a GA quality level are stable, and will not introduce backwards-incompatible changes in any minor or patch releases. We will address issues and requests with the highest priority. If we were to make a backwards-incompatible changes on an API, we will first mark the existing API as deprecated and keep it for 18 months before removing it.

Beta: Libraries defined at a Beta quality level are expected to be mostly stable and we're working towards their release candidate. We will address issues and requests with a higher priority. There may be backwards incompatible changes in a minor version release, though not in a patch release. If an element is part of an API that is only meant to be used by exporters or other OpenTelemetry libraries, then there is no deprecation period. Otherwise, we will deprecate it for 18 months before removing it, if possible.