OpenTelemetry .NET instrumentation

OpenTelemetry is the supported way to send traces, metrics, and logs from a .NET application to Osuite. There are two paths, and you pick one per service.

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

/osuite-instrument dotnet

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

Two ways to instrument .NET

• SDK in code — add the OpenTelemetry packages and configure them in Program.cs. You control which instrumentations load, and you can create custom spans and metrics. This is the recommended path for services you build and deploy yourself.
• Zero-code automatic instrumentation — the OpenTelemetry.AutoInstrumentation distribution attaches to your process through the CLR profiler and instruments supported libraries without any code change. Use it when you cannot modify the application or want a fast path across many services.

Both paths export over OTLP to the same Osuite ingest endpoint and are configured with the same environment variables.

	SDK in code	Zero-code automatic
Code changes	Required (Program.cs)	None
Custom spans and metrics	Yes	No (add the SDK to extend)
Attaches via	Package references	CLR profiler
Best for	Services you own	Existing or third-party apps

Choose your path

ASP.NET Core with the SDK Add the OpenTelemetry packages and configure tracing, metrics, and logging in Program.cs.

Custom instrumentation Create your own spans with ActivitySource and metrics with the Meter API, then register them with the SDK.

Troubleshooting Fix missing spans, IIS environment variables, and exporter connectivity.

Zero-code automatic instrumentation

Follow these steps to instrument a .NET service without changing its code. The installer downloads the automatic instrumentation, and the environment variables point it at Osuite.

1. Download and install the automatic instrumentation.

   Bare host

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

   Docker

   FROM mcr.microsoft.com/dotnet/aspnet:8.0
   
   RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*
   RUN curl -L -O https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/otel-dotnet-auto-install.sh \
       && sh ./otel-dotnet-auto-install.sh
   
   COPY bin/Release/net8.0/publish/ /app/
   WORKDIR /app
   
   ENTRYPOINT ["sh", "-c", ". /root/.otel-dotnet-auto/instrument.sh && dotnet MyApp.dll"]

   Kubernetes

   Install the automatic instrumentation in the image (see the Docker tab), then set the environment variables on the container.

   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>'

2. Set the Osuite environment variables. The automatic instrumentation exports over OTLP by default, so only the endpoint, token, and resource attributes are required.

   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

   docker run \
     -e OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.<region>.osuite.io:443 \
     -e OTEL_EXPORTER_OTLP_HEADERS=x-osuite-ingest-token=<your-ingest-token> \
     -e OTEL_SERVICE_NAME=my-service \
     -e OTEL_RESOURCE_ATTRIBUTES=service.environment=production \
     registry.example.com/my-service:latest

   Kubernetes

   The environment variables are set on the container in the previous step.

3. Load the instrumentation into the current shell and run the application. On a bare host, source instrument.sh before starting the process; the Docker and Kubernetes tabs do this in the container entrypoint.

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

Note

The automatic instrumentation defaults to the http/protobuf OTLP protocol. If your network only allows gRPC, set OTEL_EXPORTER_OTLP_PROTOCOL=grpc. The endpoint stays the same.

The service appears in APM within a minute of receiving traffic. If nothing arrives, see Troubleshooting.