Skip to content

Latest commit

 

History

History
154 lines (121 loc) · 4.96 KB

README.md

File metadata and controls

154 lines (121 loc) · 4.96 KB

OpenTelemetry .NET SDK

NuGet NuGet

Installation

dotnet add package OpenTelemetry

Introduction

OpenTelemetry SDK is a reference implementation of the OpenTelemetry API. It implements the Tracing API, the Metrics API, and the Context API. OpenTelemetry SDK deals with concerns such as sampling, processing pipeline, exporting telemetry to a particular backend etc. The default implementation consists of the following.

  • Set of Built-in samplers
  • Set of Built-in processors.
    • SimpleProcessor which sends Activities to the exporter without any batching.
    • BatchingProcessor which batches and sends Activities to the exporter.
  • Extensibility options for users to customize SDK.

Getting started

Please follow the tutorial and get started in 5 minutes.

Configuration

Instrumentation

Processor

Resource

Sampler

Samplers are used to control the noise and overhead introduced by OpenTelemetry by reducing the number of samples of traces collected and sent to the backend. If no sampler is explicitly specified, the default is to use AlwaysOnSampler. The following example shows how to change it to ProbabilitySampler with sampling probability of 25%.

using OpenTelemetry;
using OpenTelemetry.Trace;
using OpenTelemetry.Trace.Samplers;

using var otel = Sdk.CreateTracerProvider(b => b
    .AddActivitySource("MyCompany.MyProduct.MyLibrary")
    .SetSampler(new ProbabilitySampler(0.25))
    .UseConsoleExporter());

Advanced topics

Building your own Exporter

Trace Exporter

  • Exporters should inherit from ActivityExporter and implement ExportAsync and ShutdownAsync methods.
  • Depending on user's choice and load on the application ExportAsync may get called concurrently with zero or more activities.
  • Exporters should expect to receive only sampled-in ended activities.
  • Exporters must not throw.
  • Exporters should not modify activities they receive (the same activity may be exported again by different exporter).
class MyExporter : ActivityExporter
{
    public override Task<ExportResult> ExportAsync(
        IEnumerable<Activity> batch, CancellationToken cancellationToken)
    {
        foreach (var activity in batch)
        {
            Console.WriteLine(
                $"[{activity.StartTimeUtc:o}] " +
                $"{activity.DisplayName} " +
                $"{activity.Context.TraceId.ToHexString()} " +
                $"{activity.Context.SpanId.ToHexString()}"
            );
        }

        return Task.FromResult(ExportResult.Success);
    }

    public override Task ShutdownAsync(CancellationToken cancellationToken)
    {
        return Task.CompletedTask;
    }

    protected override void Dispose(bool disposing)
    {
        // flush the data and clean up the resource
    }
}
  • Users may configure the exporter similarly to other exporters.
  • You should also provide additional methods to simplify configuration similarly to UseZipkinExporter extension method.
Sdk.CreateTracerProvider(b => b
    .AddActivitySource(ActivitySourceName)
    .UseMyExporter();

Building your own Sampler

  • Samplers should inherit from Sampler, and implement ShouldSample method.
  • ShouldSample should not block or take long time, since it will be called on critical code path.
class MySampler : Sampler
{
    public override SamplingResult ShouldSample(in SamplingParameters samplingParameters)
    {
        var shouldSample = true;

        return new SamplingResult(shouldSample);
    }
}

References