Get started with BugsRadar

Connect a .NET application in a few minutes: a project and a channel in the web app, then one NuGet package in your code.

Quick start

1. Create a project. Sign in at app.bugsradar.com with your email and open the link from the email in the same browser: it signs you in and creates your account the first time. Press New project and copy the project's API key.
2. Add a channel. On the project's page press Add channel and choose Telegram, Discord or Pushover. BugsRadar checks the credentials with the service before saving them; Send test sends a test message.
3. Install the package and register it with the key.
4. Try it. Log a test exception at the Error level: it arrives in your channel.

Not sure which key an application uses? The Check API Key page of the web app shows which of your projects a key belongs to.

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 return at once. SendAsync and SendExceptionAsync complete when the event has been handed to the server. 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

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

Channels

BugsRadar delivers through your own credentials. They are checked with the service when you save the channel, stored encrypted and never shown again — only a mask such as …a1b2. Credentials can't be edited: to change a token or a webhook, create a new channel and delete the old one. One channel can serve several projects.

Telegram

1. Open @BotFather in Telegram, send /newbot and choose a name and a username. BotFather replies with the bot token, such as 123456789:AA…. Keep it secret: whoever has it controls the bot.
2. Add the bot to the group that should receive errors. For alerts to yourself, open a chat with the bot and press Start. For a Telegram channel, add the bot as an administrator that can post messages.
3. Find the chat ID: send /start in that chat (in a group: /start@your_bot_name), then open https://api.telegram.org/bot<token>/getUpdates in the browser and copy the number after "chat":{"id":. Group and channel IDs are negative, such as -1001234567890.
4. In BugsRadar, add a Telegram channel and paste the token and the chat ID.

Discord

1. In Discord, open the settings of the channel that should receive errors: Edit Channel → Integrations → Webhooks → New Webhook. This needs the Manage Webhooks permission on the server.
2. Name the webhook, for example BugsRadar, and press Copy Webhook URL.
3. In BugsRadar, add a Discord channel and paste the URL.

Pushover

1. Sign in at pushover.net. Your user key is on the dashboard. To notify several people, create a delivery group and use its key instead.
2. Create an application — Create an Application/API Token on the dashboard — and copy its API token.
3. In BugsRadar, add a Pushover channel with the application token and the user or group key.

When a channel fails

If the service is briefly unavailable or asks BugsRadar to slow down, delivery pauses and resumes on its own. If the service keeps refusing — the token was revoked, the bot was removed from the chat, the webhook was deleted — BugsRadar turns the channel off and marks it Turned off by BugsRadar with the last error; messages that were waiting for it are dropped.

Fix the cause and press Check again: BugsRadar checks the credentials with the service and turns the channel back on. The channel's On / Paused switch is yours alone and never clears a turn-off by BugsRadar.

What you receive

Three kinds of messages, one rule: a full message while your channel keeps up, a bundle when it can't. The mark shows the level: 🟥 Critical, 🔴 Error, 🟠 Warning, 🔵 Information. The samples below are from Telegram. Discord gets the same content; Pushover, a short push notification, comes without the stack trace.

The first occurrence

A new error arrives at once: the project, the level, the exception and its message, where it happened, the environment, host, version and time, the event's properties and the stack trace.

at Shop.Payments.PaymentService.ChargeAsync(Order order)
at Shop.Orders.OrderService.CreateOrder(Int32 orderId)

Summaries

While the error keeps happening, its repeats are counted and arrive as one summary: the first 10 minutes after the first message, the next after 30 minutes, then after an hour, then every 6 hours. When a window passes without repeats, the error is closed, and its next occurrence arrives as a new first message.

Bundles

When your channel can't keep up — errors have been waiting in its queue, the service asked for a pause, or a project has sent many messages within the hour — BugsRadar bundles the waiting errors into one message: a line per error with its type, place and count, grouped by project, without stack traces.

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.1 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.

Help

Something doesn't arrive, or the docs don't answer your question? Write to support@bistriy.com. Problems on the way from your application to BugsRadar are logged by the package under the BugsRadar.Client category — include those lines in your email.