ASP.NET Core OpenTelemetry instrumentation

This guide adds the OpenTelemetry .NET SDK to an ASP.NET Core service and configures it to send traces, metrics, and logs to Osuite. It uses OpenTelemetry.Extensions.Hosting to register instrumentation in Program.cs and the OTLP exporter to ship the data.

Fastest path. Run this in your AI IDE and the Instrumentation Agent wires this service up for you.

/osuite-instrument aspnet-core

Prefer to do it by hand? Follow the manual steps below — they are the complete path.

Prerequisites

• .NET 8.0 or later and an ASP.NET Core project with a Program.cs.
• An Osuite ingest endpoint and token for your region.
• Outbound network access to ingest.<region>.osuite.io on port 443.

Instrument the service

1. Install the OpenTelemetry 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
   dotnet add package OpenTelemetry.Instrumentation.Runtime

2. Configure OpenTelemetry in Program.cs. Register tracing and metrics through AddOpenTelemetry(), add logging through builder.Logging, and attach the OTLP exporter to each signal. The exporter reads its endpoint and headers from the environment variables set in the next step.

   using OpenTelemetry.Logs;
   using OpenTelemetry.Metrics;
   using OpenTelemetry.Trace;
   
   var builder = WebApplication.CreateBuilder(args);
   
   builder.Services.AddOpenTelemetry()
       .WithTracing(tracing => tracing
           .AddAspNetCoreInstrumentation()
           .AddHttpClientInstrumentation()
           .AddOtlpExporter())
       .WithMetrics(metrics => metrics
           .AddAspNetCoreInstrumentation()
           .AddHttpClientInstrumentation()
           .AddRuntimeInstrumentation()
           .AddOtlpExporter());
   
   builder.Logging.AddOpenTelemetry(logging =>
   {
       logging.IncludeScopes = true;
       logging.IncludeFormattedMessage = true;
       logging.AddOtlpExporter();
   });
   
   var app = builder.Build();
   
   app.MapGet("/", () => "Hello from Osuite");
   
   app.Run();

3. Set the Osuite environment variables. The OTLP exporter and the resource are configured entirely from the environment, so the same code runs in every environment.

   Bare host

   export OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.<region>.osuite.io:443
   export OTEL_EXPORTER_OTLP_HEADERS=x-osuite-ingest-token=<your-ingest-token>
   export OTEL_SERVICE_NAME=my-service
   export OTEL_RESOURCE_ATTRIBUTES=service.environment=production

   Docker

   FROM mcr.microsoft.com/dotnet/aspnet:8.0
   WORKDIR /app
   COPY bin/Release/net8.0/publish/ ./
   
   ENV OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.<region>.osuite.io:443
   ENV OTEL_EXPORTER_OTLP_HEADERS=x-osuite-ingest-token=<your-ingest-token>
   ENV OTEL_SERVICE_NAME=my-service
   ENV OTEL_RESOURCE_ATTRIBUTES=service.environment=production
   
   ENTRYPOINT ["dotnet", "MyApp.dll"]

   Kubernetes

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: my-service
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: my-service
     template:
       metadata:
         labels:
           app: my-service
       spec:
         containers:
           - name: my-service
             image: registry.example.com/my-service:latest
             env:
               - name: OTEL_EXPORTER_OTLP_ENDPOINT
                 value: "https://ingest.<region>.osuite.io:443"
               - name: OTEL_EXPORTER_OTLP_HEADERS
                 valueFrom:
                   secretKeyRef:
                     name: osuite-ingest
                     key: otlp-headers
               - name: OTEL_SERVICE_NAME
                 value: "my-service"
               - name: OTEL_RESOURCE_ATTRIBUTES
                 value: "service.environment=production"

   Create the secret once, holding the full header string:

   kubectl create secret generic osuite-ingest \
     --from-literal=otlp-headers='x-osuite-ingest-token=<your-ingest-token>'

4. Run the service and send it some traffic.

   dotnet run

Note

The .NET OTLP exporter defaults to the gRPC protocol, which works against ingest.<region>.osuite.io:443 over TLS. If your network only allows HTTP, set OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf; the endpoint stays the same.

Framework gotchas

IIS reads environment variables differently

When the app runs behind IIS with in-process hosting, the ASP.NET Core Module starts the worker inside the IIS process, so shell export values do not reach it. Set the variables in web.config under <aspNetCore><environmentVariables>, or on the application pool. Standalone Kestrel reads the process environment directly and needs no extra configuration.

Note

service.environment is not derived from ASPNETCORE_ENVIRONMENT. Set it explicitly in OTEL_RESOURCE_ATTRIBUTES so traces, metrics, and logs are grouped under the right environment in Osuite.

Instrumentation covers both minimal APIs and controller-based apps with no additional configuration. AddHttpClientInstrumentation traces outbound HttpClient calls so requests to downstream services join the same trace.

Verify in Osuite

What you should see

The service appears in APM within a minute of receiving traffic, emitting request-rate, latency, and error-rate metrics. Open a trace to see the ASP.NET Core server span with any outbound HttpClient spans nested beneath it, and confirm application logs appear in Logs correlated to the same trace.

Troubleshooting

No data in Osuite after a few minutes? Work through these checks.

• Endpoint — confirm the exporter targets exactly ingest.<region>.osuite.io:443 for your region, over TLS.
• Token — confirm the ingest header carries a valid <your-ingest-token> and has not been rotated.
• Pipeline — confirm the signal you expect (traces, logs, or metrics) is wired into an active pipeline with the otlp/osuite exporter attached.
• Export errors — check the application or Collector logs for OTLP export failures (auth, DNS, TLS, connection refused).
• Network — confirm the host has outbound access to the ingest endpoint on port 443.
• Timing — allow up to a minute for the first data to appear before assuming a failure.

Still stuck? Ask the Investigation Agent or contact support.

See .NET troubleshooting for issues specific to the SDK, such as missing ActivitySource registration and IIS environment variables.

Next steps

• Custom instrumentation — add your own spans and metrics.
• Trace correlation for logs — link logs to traces across services.