Integration Guide

Add professional-grade observability to your .NET application using OpenTelemetry.

Step 1: Install the package

dotnet add package PrimusSaaS.Observability

Step 2: Configure Program.cs

using PrimusSaaS.Observability;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddPrimusObservability(builder.Configuration, "MY-SERVICE-NAME");

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

Step 3: Configure appsettings.json

{
  "PrimusObservability": {
    "OtlpEndpoint": "http://localhost:4317",
    "SamplingRatio": 0.2,
    "UseConsole": true
  }
}

How to get configuration values

• OtlpEndpoint is the OTLP endpoint for your collector (local or hosted).
• SamplingRatio controls the percentage of traces captured (0.0 to 1.0).
• UseConsole enables console export for local development.

Step 4: Configure endpoint

No special endpoints are required. Any existing API endpoint will emit telemetry. If you want a simple test endpoint:

app.MapGet("/health", () => Results.Ok(new { status = "ok" }));

Step 5: Test the endpoint

curl http://localhost:5000/health

Verify traces and metrics in your collector or backend.

---

Technical Specifications

Feature	Default Value	Description
Sampling Ratio	1.0 (100%)	Controls the percentage of traces captured.
OTLP Protocol	gRPC/Protobuf	Standard W3C TraceContext propagation.
Automatic Scopes	Enabled	Injects TraceID and SpanID into all ILogger calls.

---

Supported Backends

Because Primus uses the OTLP Standard, you can connect to almost any tool:

Local Development (Aspire / Jaeger)

For a visual trace dashboard on your local machine, run Jaeger and point the endpoint to http://localhost:4317.

Azure Monitor / Application Insights

To send data to Azure, use the Azure Monitor OpenTelemetry Distro.

Prometheus & Grafana

Configure an OpenTelemetry Collector to scrape your metrics and export them to Prometheus.

---

Advantages

1. Reduce Dev Time: OTel traces methods and spans automatically.
2. Accuracy: Trace IDs flow across service boundaries.
3. Future Proof: Change providers with zero code changes.