Skip to content

Latest commit

 

History

History
143 lines (114 loc) · 4.88 KB

README.md

File metadata and controls

143 lines (114 loc) · 4.88 KB
Raw

Getting Started with OpenTelemetry .NET in 5 Minutes

First, download and install the .NET SDK on your computer.

Create a new console application and run it:

dotnet new console --output getting-started
cd getting-started
dotnet run

You should see the following output:

Hello World!

Install the OpenTelemetry.Exporter.Console package:

dotnet add package OpenTelemetry.Exporter.Console

Update the Program.cs file with the code from Program.cs:

Run the application again (using dotnet run) and you should see the trace output from the console.

Activity.TraceId:          d4a7d499698d62f0e2317a67abc559b6
Activity.SpanId:           a091d18fbe45bdf6
Activity.TraceFlags:           Recorded
Activity.ActivitySourceName: MyCompany.MyProduct.MyLibrary
Activity.DisplayName: SayHello
Activity.Kind:        Internal
Activity.StartTime:   2022-03-30T19:42:33.5178011Z
Activity.Duration:    00:00:00.0097620
StatusCode : Ok
Activity.Tags:
    foo: 1
    bar: Hello, World!
    baz: [1, 2, 3]
Resource associated with Activity:
    service.name: unknown_service:getting-started

Congratulations! You are now collecting traces using OpenTelemetry.

What does the above program do?

The program creates an ActivitySource which represents an OpenTelemetry Tracer.

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

The ActivitySource instance is used to start an Activity which represents an OpenTelemetry Span and set several Tags, which represents Attributes on it. It also sets the Status to be Ok.

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

An OpenTelemetry TracerProvider is configured to subscribe to the activities from the source MyCompany.MyProduct.MyLibrary, and export it to ConsoleExporter. ConsoleExporter simply displays it on the console.

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource("MyCompany.MyProduct.MyLibrary")
    .AddConsoleExporter()
    .Build();
graph LR

subgraph SDK
  TracerProvider
  Processor["SimpleExportProcessor < Activity >"]
  ConsoleExporter
end

subgraph API
  ActivitySource["ActivitySource(#quot;MyCompany.MyProduct.MyLibrary#quot;)"]
end

ActivitySource --> | System.Diagnostics.Activity | TracerProvider

TracerProvider --> | System.Diagnostics.Activity | Processor --> | Batch | ConsoleExporter
Loading

TracerProvider

As shown in the above program, a valid TracerProvider must be configured and built to collect traces with OpenTelemetry .NET SDK. TracerProvider holds all the configuration for tracing like samplers, processors, etc. and is highly customizable.

OpenTelemetry .NET and relation with .NET Activity API

If you tried the above program, you may have already noticed that the terms ActivitySource and Activity were used instead of Tracer and Span from OpenTelemetry specification. This results from the fact that, Traces in OpenTelemetry .NET is a somewhat unique implementation of the OpenTelemetry project, as most of the Trace API is implemented by the .NET runtime itself. From a high level, what this means is that you can instrument your application by simply depending on System.Diagnostics.DiagnosticSource package, which provides Activity and ActivitySource classes representing the OpenTelemetry concepts of Span and Tracer respectively. Read this to learn more.

Learn more