BugsRadar for .NET

One NuGet package for ASP.NET Core, worker services, desktop and console apps: an ILogger provider, a Serilog sink and direct calls in one.

You need a BugsRadar project with a channel and the project's API key first: see Get started.

Install the package

dotnet add package BugsRadar

The package targets .NET Standard 2.0. Its dependencies are floors, not the latest versions: Microsoft.Extensions.Http 8.0, Microsoft.Extensions.Logging.Abstractions 8.0, Newtonsoft.Json 13.0.4 and Serilog 4.4.0. If your application already uses newer versions, they stay as they are.

Register the client

In an application with dependency injection — ASP.NET Core, a worker service — register BugsRadar once:

using BugsRadar.Extensions.DependencyInjection;

builder.Services.AddBugsRadar(configuration =>
{
    configuration.ApiKey = "<your project API key>";
    configuration.Environment = builder.Environment.EnvironmentName; // optional
});

Treat the key like any other secret and keep it out of source control, for example in configuration: configuration.ApiKey = builder.Configuration["BugsRadar:ApiKey"];. The key is required: an empty one throws ArgumentException when the client is created.

ILogger provider

Everything you already log at Error and above goes to BugsRadar with its message template, properties, scopes and category:

using BugsRadar.Extensions.DependencyInjection;
using BugsRadar.Extensions.Logging;

builder.Services.AddBugsRadar(c => c.ApiKey = "<your project API key>");
builder.Logging.AddBugsRadar();

logger.LogError(ex, "Order {OrderId} failed", 42) arrives with the template Order {OrderId} failed and the property OrderId = 42. The minimum level is BugsRadarConfiguration.MinimumLevel, Error by default.

Serilog sink

Serilog configured before the host exists:

using BugsRadar.Extensions.Serilog;

Log.Logger = new LoggerConfiguration()
    .WriteTo.BugsRadar("<your project API key>")
    .CreateLogger();

Serilog configured with dependency injection, sharing the client registered with AddBugsRadar:

builder.Host.UseSerilog((context, services, configuration) => configuration
    .WriteTo.BugsRadar(services));

The sink takes Error and above by default (restrictedToMinimumLevel). When the sink owns the client (the first form), delivery problems are written to Serilog's SelfLog: turn it on with SelfLog.Enable(Console.Error).

Direct calls

Inject IBugsRadar and report exceptions or your own events:

using BugsRadar;

public class OrderService
{
    private readonly IBugsRadar _bugsRadar;

    public OrderService(IBugsRadar bugsRadar)
    {
        _bugsRadar = bugsRadar;
    }

    public void CreateOrder(int orderId)
    {
        try
        {
            // ...
        }
        catch (Exception error)
        {
            _bugsRadar.SendException(error, "OrderService : CreateOrder", module: "Orders");

            // or the full model
            _bugsRadar.Send(new BugsRadarEvent
            {
                Exception = error,
                MessageTemplate = "Order {OrderId} failed",
                Message = $"Order {orderId} failed",
                Properties = { ["OrderId"] = orderId.ToString() },
                Module = "Orders"
            });
        }
    }
}

Send and SendException queue the event and return at once, so reporting an error never adds network time to your own code. The only method that waits for the network is FlushAsync, for a process that is about to exit. Nothing throws: delivery problems are written to ILogger under the category BugsRadar.Client.

BugsRadar groups repeats of an error by a fingerprint it computes from the exception type and the top frames of the stack, or from the message template. To group by your own key, set Fingerprint on the event.

Console apps and scripts

using BugsRadar;

using var bugsRadar = new BugsRadarClient(new BugsRadarConfiguration { ApiKey = "<your project API key>" });

bugsRadar.SendException(error);

await bugsRadar.FlushAsync(); // before exit; Dispose also drains the queue

A script that isn't .NET — Bash, PowerShell, a CI step, a SQL Server Agent job — sends an alert with one HTTP request: see Send alerts from any script.

How events travel

• Events go to an in-process queue and are sent in the background; your code never waits for the network.
• Repeats of the same error within RepeatInterval (5 seconds) are folded into one request with a count. A crash loop costs one request every few seconds, not thousands per second.
• The same exception instance seen twice — logged and reported by hand, or by ILogger and Serilog — is sent once.
• On 429 the client waits as long as the server asks; on 5xx and network failures it retries three times.
• When the application stops, Dispose drains the queue for ShutdownTimeout (10 seconds).

Configuration

Upgrading from 1.x

API v2 is shut down: versions of the package below 3.0.0.1 no longer deliver error reports and are not supported. Update to 3.0.0.2 or later. The package major version matches the API version it talks to: 3.x uses API v3.

The package no longer depends on ASP.NET Core. If your application calls AddNewtonsoftJson and relied on BugsRadar 1.x to bring it in, reference Microsoft.AspNetCore.Mvc.NewtonsoftJson directly.

3.0.0.2 removes SendAsync and SendExceptionAsync. They completed only once the event had been delivered, so awaiting one inside a catch put a network round trip into the path of your own request. Send and SendException give you the same duplicate filtering, repeat aggregation and retries without the wait; call FlushAsync before a short-lived process exits.

Something doesn't arrive? Problems on the way from your application to BugsRadar are logged under the BugsRadar.Client category — include those lines when you write to support@bistriy.com.