.NET Quickstart

This guide gets you from zero to your first captured trace in a .NET service.

Prerequisites

.NET 8, 9, or 10
An Incidentary workspace and API key (from the dashboard under Settings → API Keys)

Install

dotnet add package Incidentary.Sdk
dotnet add package Incidentary.Sdk.AspNetCore

Initialize the client

using Incidentary.Sdk;
using Incidentary.Sdk.AspNetCore;

var client = new IncidentaryClient(new IncidentaryClientOptions
{
    ApiKey      = Environment.GetEnvironmentVariable("INCIDENTARY_API_KEY")!,
    ServiceName = "my-service",
});

That's the core setup. The SDK automatically instruments outbound HTTP calls via IHttpClientFactory, supported queue libraries, databases, and gRPC — no additional code needed.

Mount inbound middleware

ASP.NET Core (minimal API or MVC)

app.UseIncidentary(client);

Place it early in the pipeline, before routing, so every request is captured.

Dependency injection

Use the DI extension to register the client with the host container:

dotnet add package Incidentary.Sdk.Extensions.DependencyInjection

builder.Services.AddIncidentary(options =>
{
    options.ApiKey      = builder.Configuration["Incidentary:ApiKey"]!;
    options.ServiceName = "my-service";
});

Then inject IIncidentaryClient anywhere in your application.

Outbound HTTP — automatic

Add the HTTP extension to auto-instrument outbound calls via HttpClient:

dotnet add package Incidentary.Sdk.Extensions.Http

builder.Services.AddHttpClient("downstream")
    .AddIncidentaryHandler(client);

Every outbound request automatically gets x-incidentary-trace-id and x-incidentary-parent-ce headers injected.

Integrations

gRPC

dotnet add package Incidentary.Sdk.Integrations.Grpc

builder.Services.AddGrpc(options =>
{
    options.Interceptors.Add<IncidentaryServerInterceptor>();
});

MassTransit

dotnet add package Incidentary.Sdk.Integrations.MassTransit

builder.Services.AddMassTransit(x =>
{
    x.AddIncidentary(client);
    // ... your consumers and transports
});

Entity Framework Core

dotnet add package Incidentary.Sdk.Integrations.EntityFrameworkCore

optionsBuilder.UseIncidentary(client);

AWS Lambda

dotnet add package Incidentary.Sdk.Lambda

[assembly: LambdaSerializer(typeof(DefaultLambdaJsonSerializer))]

public class Function
{
    private static readonly IIncidentaryClient _client = new IncidentaryClient(
        new IncidentaryClientOptions
        {
            ApiKey      = Environment.GetEnvironmentVariable("INCIDENTARY_API_KEY")!,
            ServiceName = "my-lambda",
        });

    public async Task<APIGatewayProxyResponse> FunctionHandler(
        APIGatewayProxyRequest request,
        ILambdaContext context)
    {
        using var scope = _client.StartLambdaScope(request, context);
        // your handler logic
        return new APIGatewayProxyResponse { StatusCode = 200 };
    }
}

Recording custom events

client.RecordQueuePublish(new RecordEventOptions { EventAttrs = new() { ["topic"] = "orders.created" } });
client.RecordQueueConsume();
client.RecordJobStart(new RecordEventOptions { EventAttrs = new() { ["worker"] = "invoice-sync" } });
client.RecordJobEnd();
client.RecordWebhookIn();
client.RecordWebhookOut(202);

Environment variables

Variable	Required	Default	Description
`INCIDENTARY_API_KEY`	Yes	—	Workspace API key (`sk_...`) from the dashboard
`INCIDENTARY_SERVICE_NAME`	No	—	Alternative to passing `ServiceName` in code
`INCIDENTARY_ENVIRONMENT`	No	`production`	Environment label (`production`, `staging`, etc.)
`INCIDENTARY_API_URL`	No	`https://api.incidentary.com`	Override for self-hosted or local dev

Verify capture

After deploying with the SDK installed:

Make a request to your service
Open the Incidentary dashboard → Traces
A trace should appear within a few seconds

If no trace appears within 30 seconds, see the troubleshooting section below.

What happens during an incident

When an alert fires (via Slack, PagerDuty, or OpsGenie), Incidentary assembles the causal chain from events your service has already captured. The SDK continuously maintains a rolling window of recent activity — events from before the alert fired are included in the assembled artifact.

The SDK does not create incidents or page anyone. It is passive until an alert arrives.

Troubleshooting

401 Unauthorized on ingest: You are using a user session token, not a workspace API key. API keys start with sk_ and are found in Settings → API Keys.

No traces in the dashboard: Ensure your process calls FlushToBackendAsync() before shutdown. In Lambda, call it explicitly at the end of each invocation.

426 SDK_VERSION_TOO_OLD: Upgrade to Incidentary.Sdk 0.2.0 or newer via dotnet add package Incidentary.Sdk.

Services not linked: You are not propagating the x-incidentary-trace-id and x-incidentary-parent-ce headers on outbound calls. Use Incidentary.Sdk.Extensions.Http to auto-inject them.

.NET

On this page