This guide provides step-by-step instructions for setting up OpenTelemetry (OTel) instrumentation in your .Net applications to enable comprehensive observability. OpenTelemetry is an open-source framework that helps you collect telemetry data—such as traces, metrics, and logs—from your app to monitor its performance and health.

Once your telemetry data is captured, you can configure an exporter to send it directly to Atatus for advanced monitoring and insights.

The process of setting up OpenTelemetry in .Net involves three key steps:

Instrumenting Your .Net Application: Add the necessary OpenTelemetry components to your .Net app for trace and metric collection.
Configuring the Exporter: Set up the exporter to send your telemetry data to Atatus.
Validating the Setup: Verify that the configuration is working and that your data is being correctly sent to Atatus.

Sending Telemetry Data to Atatus in Two Ways

Send Telemetry Traces to Atatus

Option 1: No Code Automatic Instrumentation (recommended)
Option 2: Code Level Automatic Instrumentation

Send Traces Using the OTel Collector Binary

Option 1: No Code Automatic Instrumentation (recommended)
Option 2: Code Level Automatic Instrumentation

Requirements

.NET SDK (.NET 5.0 or Later)

Send Telemetry Traces to Atatus

Option 1: No Code Automatic Instrumentation

  1. Create a shell script with the following content You can either create a bash script with the following content or paste this directly into your terminal after replacing SERVICE_NAME, ATATUS_ENDPOINT and ATATUS_INGESTION_KEY

     # Download the bash script
curl -sSfL https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/otel-dotnet-auto-install.sh -O

# Install core files
sh ./otel-dotnet-auto-install.sh

# Enable execution for the instrumentation script
chmod +x $HOME/.otel-dotnet-auto/instrument.sh

# Setup the instrumentation for the current shell session
. $HOME/.otel-dotnet-auto/instrument.sh

# Run your application with instrumentation
OTEL_SERVICE_NAME=<SERVICE_NAME> OTEL_TRACES_EXPORTER=otlp OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf OTEL_RESOURCE_ATTRIBUTES=deployment.environment=staging,service.version=1.0.0 OTEL_EXPORTER_OTLP_ENDPOINT=<ATATUS_ENDPOINT> OTEL_EXPORTER_OTLP_HEADERS=api-key=<ATATUS_INGESTION_KEY> ./MyNetApp

Option 2: Code Level Automatic Instrumentation

  1. Installing the OpenTelemetry dependency packages:

    dotnet add package OpenTelemetry
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
dotnet add package OpenTelemetry.Extensions.Hosting
dotnet add package OpenTelemetry.Instrumentation.Runtime
dotnet add package OpenTelemetry.Instrumentation.AspNetCore
dotnet add package OpenTelemetry.AutoInstrumentation

  2. Adding OpenTelemetry as a service and configuring exporter options in Program.cs

    using System.Diagnostics;
using OpenTelemetry.Exporter;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

var builder = WebApplication.CreateBuilder(args);

// Configure OpenTelemetry with tracing and auto-start.
builder.Services.AddOpenTelemetry()
    .ConfigureResource(resource =>
    resource.AddService(serviceName: "sample-net-app"))
    .WithTracing(tracing => tracing
        .AddAspNetCoreInstrumentation()
        .AddOtlpExporter(otlpOptions =>
        {
            otlpOptions.Endpoint = new Uri("https://otel-rx.atatus.com:443");

            otlpOptions.Protocol = OtlpExportProtocol.Grpc;

            string headerKey = "api-key";
            string headerValue = "<ATATUS_INGESTION_KEY>";

            string formattedHeader = $"{headerKey}={headerValue}";
            otlpOptions.Headers = formattedHeader;
        }));

var app = builder.Build();

// The index route ("/") is set up to write out the OpenTelemetry trace information on the response:
app.MapGet("/", () => $"Hello World! OpenTelemetry Trace: {Activity.Current?.Id}");

app.Run();

  3. Running the .NET application:

    dotnet build
dotnet run

Send Traces Using the OTel Collector Binary:

To collect and send traces to Atatus, it's recommended to install the OpenTelemetry (OTel) Collector binary. The OTel Collector helps gather logs, host metrics, resource, and infrastructure attributes, enabling richer contextual data and easier signal correlation.

For detailed instructions on setting up the OTel Collector binary on your VM, please refer to the official installation guide. Once the Collector is up and running, you can proceed with instrumenting your Java application to start sending telemetry data to Atatus.

Option 1: No Code Automatic Instrumentation

  1. Create a shell script with the following content You can either create a bash script with the following content or paste this directly into your terminal after replacing SERVICE_NAME, ATATUS_ENDPOINT and ATATUS_INGESTION_KEY

    curl -sSfL https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/otel-dotnet-auto-install.sh -O

sh ./otel-dotnet-auto-install.sh

chmod +x $HOME/.otel-dotnet-auto/instrument.sh

. $HOME/.otel-dotnet-auto/instrument.sh

OTEL_SERVICE_NAME=<SERVICE_NAME> OTEL_TRACES_EXPORTER=otlp OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf OTEL_RESOURCE_ATTRIBUTES=deployment.environment=staging,service.version=1.0.0 OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces ./MyNetApp

Option 2: Code Level Automatic Instrumentation

  1. Installing the OpenTelemetry dependency packages:

    dotnet add package OpenTelemetry
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
dotnet add package OpenTelemetry.Extensions.Hosting
dotnet add package OpenTelemetry.Instrumentation.Runtime
dotnet add package OpenTelemetry.Instrumentation.AspNetCore
dotnet add package OpenTelemetry.AutoInstrumentation

  2. Adding OpenTelemetry as a service and configuring exporter options in Program.cs

    using System.Diagnostics;
using OpenTelemetry.Exporter;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

var builder = WebApplication.CreateBuilder(args);

// Configure OpenTelemetry with tracing and auto-start.
builder.Services.AddOpenTelemetry()
    .ConfigureResource(resource =>
    resource.AddService(serviceName: "payment-server"))
    .WithTracing(tracing => tracing
        .AddAspNetCoreInstrumentation()
        .AddOtlpExporter(otlpOptions =>
        {
            otlpOptions.Endpoint = new Uri("http://localhost:4317");

            otlpOptions.Protocol = OtlpExportProtocol.Grpc;
        }));

var app = builder.Build();

//The index route ("/") is set up to write out the OpenTelemetry trace information on the response:
app.MapGet("/", () => $"Hello World! OpenTelemetry Trace: {Activity.Current?.Id}");

app.Run();

  3. Running the .NET application:

    dotnet build
dotnet run