.NET manual instrumentation (SDK)

With manual instrumentation, you install the OpenTelemetry .NET SDK packages yourself and add the trace setup code to the application. Use this instead of automatic instrumentation (the Kubernetes, IIS and Linux VM guides). It works the same on Kubernetes and on VMs.

Step 1: Install the packages

dotnet add package OpenTelemetry.Extensions.Hosting
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
dotnet add package OpenTelemetry.Instrumentation.AspNetCore
dotnet add package OpenTelemetry.Instrumentation.Http

Package	Purpose
`OpenTelemetry.Extensions.Hosting`	Registers OpenTelemetry in the ASP.NET Core host
`OpenTelemetry.Exporter.OpenTelemetryProtocol`	Sends traces over OTLP
`OpenTelemetry.Instrumentation.AspNetCore`	Spans for incoming requests
`OpenTelemetry.Instrumentation.Http`	Spans for outgoing `HttpClient` calls

For other libraries, add their instrumentation packages too, for example OpenTelemetry.Instrumentation.SqlClient or OpenTelemetry.Instrumentation.EntityFrameworkCore.

Step 2: Add the setup code

In Program.cs:

using OpenTelemetry.Exporter;
using OpenTelemetry.Trace;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing
        .AddAspNetCoreInstrumentation()         // incoming requests
        .AddHttpClientInstrumentation()         // outgoing HttpClient calls
        .AddOtlpExporter(options =>
            options.Protocol = OtlpExportProtocol.HttpProtobuf));   // endpoint from OTEL_EXPORTER_OTLP_ENDPOINT

var app = builder.Build();
app.Run();

The service name and the kubesense.* attributes are read from OTEL_SERVICE_NAME and OTEL_RESOURCE_ATTRIBUTES.

note: The .NET OTLP exporter uses gRPC by default. KubeSense trace ingestion uses OTLP over HTTP, so keep OtlpExportProtocol.HttpProtobuf as shown.

Step 3: Configure the endpoints

Set the environment variables from Manual SDK: where to send traces:

On Kubernetes, put them in the Deployment's env.
On IIS, put them in web.config (see .NET on IIS).
On a Linux VM, put them in the systemd unit (see .NET on a Linux VM).

warning: Use either this SDK setup or automatic instrumentation for an application, not both. Running both produces duplicate spans.

Troubleshooting

Symptom	Check
No traces	Check the endpoint variables (Step 3) and that the app can reach the collector or KubeSense
Duplicate spans	Both the SDK setup and automatic instrumentation are active