Incidentary.Sdk 0.2.0

Incidentary SDK for .NET

Official .NET SDK for Incidentary. Zero-overhead instrumentation with local pre-arm anomaly detection.

Packages

Package	Description	NuGet
Incidentary.Sdk	Core library
Incidentary.Sdk.Extensions.DependencyInjection	DI registration
Incidentary.Sdk.Extensions.Http	HttpClient instrumentation
Incidentary.Sdk.AspNetCore	ASP.NET Core middleware
Incidentary.Sdk.Integrations.Grpc	gRPC interceptors
Incidentary.Sdk.Integrations.MassTransit	MassTransit filters
Incidentary.Sdk.Integrations.EntityFrameworkCore	EF Core interceptor
Incidentary.Sdk.Lambda	AWS Lambda wrapper

Quick Start

ASP.NET Core

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddIncidentary(options =>
{
    options.ApiKey = builder.Configuration["Incidentary:ApiKey"]!;
    options.ServiceName = "checkout-api";
    options.Environment = builder.Environment.EnvironmentName;
});

var app = builder.Build();
app.UseIncidentary();   // Add early in the pipeline
app.MapControllers();
app.Run();

Outbound HTTP instrumentation

builder.Services.AddHttpClient("payments-api")
    .AddIncidentaryTracing();  // Records HTTP_OUT events, propagates trace context

Event vocabulary helpers

public class OrderProcessor
{
    private readonly IIncidentaryClient _incidentary;

    public OrderProcessor(IIncidentaryClient incidentary)
    {
        _incidentary = incidentary;
    }

    public async Task ProcessAsync(Order order)
    {
        _incidentary.RecordJobStart();

        // ... process order ...

        _incidentary.RecordJobEnd(new RecordEventOptions { Status = 200 });
    }
}

Available helpers: RecordQueuePublish, RecordQueueConsume, RecordJobStart, RecordJobEnd, RecordWebhookIn, RecordWebhookOut.

gRPC instrumentation

// Server
services.AddGrpc(options =>
{
    options.Interceptors.Add<IncidentaryServerInterceptor>();
});

// Client
var channel = GrpcChannel.ForAddress("https://api.internal");
var invoker = channel.Intercept(new IncidentaryClientInterceptor(incidentaryClient));

EF Core instrumentation

services.AddDbContext<AppDbContext>(options =>
{
    options.UseNpgsql(connectionString);
    options.AddInterceptors(new IncidentaryDbCommandInterceptor(incidentaryClient));
});

AWS Lambda

public class Function
{
    private static readonly IncidentaryClient Client = new(new IncidentaryClientOptions
    {
        ApiKey = Environment.GetEnvironmentVariable("INCIDENTARY_API_KEY")!,
        ServiceName = "order-lambda",
        BaseUrl = "https://api.incidentary.io"
    });

    public Task<APIGatewayProxyResponse> Handler(APIGatewayProxyRequest request, ILambdaContext context) =>
        LambdaHandler.Wrap<APIGatewayProxyRequest, APIGatewayProxyResponse>(Client, async (req, ctx) =>
        {
            // Always flushes before Lambda freeze
            return new APIGatewayProxyResponse { StatusCode = 200 };
        })(request, context);
}

How it works

The SDK instruments your .NET services to capture causal events — lightweight records of what happened, when, and why. These events form a distributed causal graph that Incidentary uses to reconstruct incident timelines.

Capture modes

Local pre-arm triggers

The SDK monitors traffic patterns and auto-escalates to detailed capture before any external alert fires:

Configuration defaults

Flush behavior

• Events are buffered in a ring buffer (4,000 capacity, FIFO overwrite)
• Flushed to backend in batches of up to 500 events
• Retry backoff: 1s, 4s, 16s (3 retries, then drop)
• Circuit breaker: opens after 3 consecutive failures, 60s cooldown
• Quota pause: HTTP 429 pauses until next UTC month

Trace context propagation

The SDK propagates two headers on all outbound HTTP, gRPC, and queue calls:

x-incidentary-trace-id: <UUID>    # Groups events in a distributed trace
x-incidentary-parent-ce: <UUID>   # Names the causal parent event

Target frameworks

• .NET 8 (LTS)
• .NET 9
• .NET 10 (LTS)

Enterprise features

• Strong-named assemblies for GAC and enterprise policies
• SourceLink for debugging into SDK source from NuGet
• Deterministic builds for reproducibility
• System.Text.Json source generators for AOT compatibility
• ConfigureAwait(false) throughout for sync-over-async safety
• Fail-open semantics — SDK never throws into user code

License

Apache 2.0