Lerix 0.3.0

Lerix .NET SDK

Server-side SDK for Lerix, the developer monitoring and engagement platform. Two lines in Program.cs and every unhandled exception in your ASP.NET Core app shows up in the Lerix dashboard with its stack trace, host, release and request context. The same package gives your backend a typed client for sending push notifications to your mobile and web users.

Full documentation lives at docs.lerix.dev.

Features

Installation

dotnet add package Lerix.AspNetCore

You will need a project API key and project id from Project Settings in the dashboard.

Quick start

using Lerix.AspNetCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddLerix(o =>
{
    o.ApiKey = builder.Configuration["LERIX_API_KEY"];
    o.ProjectId = builder.Configuration["LERIX_PROJECT_ID"];
});

var app = builder.Build();
app.UseExceptionHandler("/error");
app.UseLerix();          // after UseExceptionHandler, before routing/endpoints
app.MapControllers();
app.Run();

Or bind from appsettings.json:

{ "Lerix": { "ApiKey": "...", "ProjectId": "...", "Environment": "production" } }

builder.Services.AddLerix(builder.Configuration.GetSection("Lerix"));

ApiKey and ProjectId also fall back to LERIX_API_KEY and LERIX_PROJECT_ID.

Report something you handled yourself:

public class OrdersService(LerixClient lerix)
{
    public async Task Reconcile(string orderId)
    {
        try { await ledger.Reconcile(orderId); }
        catch (Exception error)
        {
            await lerix.CaptureException(error, new CaptureOptions
            {
                Type = BugType.LogicBug,
                Metadata = new Dictionary<string, object?> { ["orderId"] = orderId },
            });
            throw;
        }
    }
}

Options

Request tracing

Off by default. Turn it on to record one span per HTTP request — route template, method, status code, duration — plus the database commands and outbound HttpClient calls it made, shown under Requests in the dashboard and inline on every error page:

builder.Services.AddLerix(o =>
{
    o.ApiKey = "...";
    o.ProjectId = "...";
    o.Tracing.Enabled = true;
});

Built on System.Diagnostics.Activity, so it needs no extra packages:

• One server span per request, taken from ASP.NET Core's own request activity and named after the route template (GET /users/{id:int}), never the raw path. An incoming W3C traceparent header is continued by the framework; UseLerix() completes the span with route, status and client address. Only requests that pass through UseLerix() are traced.

• Child spans from the runtime's instrumentation: HttpClient calls (which carry traceparent to the next service) and database drivers that publish activities — Npgsql, Microsoft.Data.SqlClient, MySqlConnector, and EF Core on top of them — with the SQL reduced to a template (SELECT * FROM users WHERE id = ?). o.Tracing.Instrumentations switches each off; AdditionalActivitySources adds your own. Anything else by hand:

  using (LerixTracing.StartChild("cache get", ActivityKind.Client, new Dictionary<string, object?> { ["server.address"] = "redis" }))
  {
      await cache.GetAsync(key);
  }
  

• Sampling: 10% of successful requests are kept in full (SampleRate); a request that failed, exceeded SlowThreshold (2 s) or reported an error is always kept. The decision is made once at the root and travels in the W3C trace flags. Every request's root span is still sent, so per-route counts and percentiles cover 100% of traffic.

• Errors carry their trace: every report made inside a request has the request's traceId/spanId; one outside any request records as before.

• Client addresses follow the policy set in Project settings → Tracing: masked by default (last IPv4 octet zeroed / IPv6 cut to /64 before the address leaves your process), hashed or full on the Lerix side; the trusted-proxy depth and header decide how it is read from X-Forwarded-For, never trusting the whole chain.

• Spans leave through a bounded queue on the thread pool as OTLP/HTTP JSON; a failed export is counted and dropped, never retried, never thrown. Counters: lerixClient.Tracing?.Stats().

• With Tracing.Enabled false (the default) no activity listener is registered and nothing changes for the application.

Push notifications

builder.Services.AddLerixNotifications(o =>
{
    o.ProjectId = builder.Configuration["MOBILE_PROJECT_ID"];
    o.ApiKey = builder.Configuration["MOBILE_PROJECT_PRIVATE_KEY"];
});

var result = await push.SendAsync(new SendNotificationInput
{
    Title = "Order shipped",
    Body = "Arrives Tuesday",
    DeviceTokens = new[] { deviceId },
});
await push.UpdateAsync(result.NotificationId, "Order shipped!", "Arrives Monday");
await push.DeliveriesAsync(result.NotificationId);
await push.UnsendAsync(result.NotificationId);

// Every device of your own users (ids passed to setUser() in the client SDKs), on every platform:
var sent = await push.SendAsync(new SendNotificationInput
{
    Title = "New reply",
    Body = "Open the thread",
    ExternalUserIds = new[] { user.Id },
});
// sent.MatchedDevices, sent.UnknownUserIds

Use one target per send (ExternalUserIds can't be combined with the others): DeviceTokens, ExternalUserIds (up to 1000), or SendByTopic with Topic. UnknownUserIds lists ids with no device yet; that is not an error.

If the project requires identity verification, compute the hash the client SDK's setUser(externalId, identityHash) needs on your server, from the project's identity secret (never ship the secret in an app):

var hash = LerixIdentity.IdentityHash(configuration["LERIX_IDENTITY_SECRET"]!, user.Id); // hex HMAC-SHA256

Errors raise LerixApiException with Code, Message and Status.

Development

dotnet test
dotnet pack -c Release -o artifacts

Tests run against an in-process Kestrel mock of the Lerix API (tests/Lerix.Tests/MockLerixApi.cs).

License

MIT