Acta. Durable execution for .NET

learn actaget told when something breaks

How to route alerts to Slack from configuration

An alert channel posts to a Slack webhook whose URL comes from configuration, and logs when none is set. A deduplication key collapses repeats of one incident into one alert.

A how-to for Acta, durable execution for .NET. New to Acta? Run your first durable job in five minutes.

Checked every release learn/400-observability-and-alerts/405-real-alert-routing
Read as

1Declare a Slack channel with its URL from configuration

Built-in Slack incoming-webhook transport, with the webhook URL from configuration (Alerts:SlackWebhookUrl). Without one the channel logs instead, so a plain run sends nothing. Acta SQL stores only channel_name = "ops-slack" either way. MinSeverity = Warning suppresses lower-severity alerts at delivery.

real-alert-routing.csexcerpt
w.AddManifest<RealAlertRoutingJobs>();

var webhookUrl = builder.Configuration["Alerts:SlackWebhookUrl"];
w.AddAlertChannel(
    "ops-slack",
    webhookUrl is null ? AlertTransportKinds.Log : AlertTransportKinds.SlackWebhook,
    endpoint: webhookUrl ?? "ops-slack",
    o =>
    {
        o.MinSeverity = AlertSeverityCode.Warning;
    }
);

2Raise the alerts of one incident under one key

deduplicationKey ties repeats together onto one open incident row. The program enqueues two checks of the same queue: both raise under one key and fold into one alert that counts two.

real-alert-routing.csexcerpt
await context.AlertAsync(
    title: $"Queue backlog: {input.Queue}",
    message: $"'{input.Queue}' depth is {input.Depth}, above the 10k threshold.",
    severityCode: AlertSeverityCode.Error,
    channelName: "ops-slack",
    deduplicationKey: $"queue-depth:{input.Queue}",
    ct: ct
);
Console.WriteLine($"[{input.Queue}] depth {input.Depth} - alerted ops-slack");
return;

3Run it and check the output

From a clone of the Acta repository, with the .NET 10 SDK:

Terminal
dotnet run --project learn/400-observability-and-alerts/405-real-alert-routing
Its output must contain
alert [Error] Queue backlog: orders -> 'ops-slack' x2

Checked every release. Before each release, Acta Verify runs this program and checks that its output contains these lines.

This page shows the code. The rules it relies on, starting with the handler running again from its first line, are in the handler contract.

The whole program

Every file of learn/400-observability-and-alerts/405-real-alert-routing, as it is compiled.

UseLocalDatabase is a helper of the Acta repository, not of the packages. In your own app, register the database with UseSqlite, UsePostgres or UseSqlServer, as in how to run your first job.

real-alert-routing.cs91 lines
real-alert-routing.cs
// How to route alerts to Slack from configuration
// An alert channel posts to a Slack webhook whose URL comes from configuration, and logs when none is set. A
// deduplication key collapses repeats of one incident into one alert.
using Acta;
using Acta.Learn.RealAlertRouting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.UseActa(j =>
{
    j.UseLocalDatabase(builder.Configuration);

    j.Run("real-alert-routing", w =>
    {
        w.AddManifest<RealAlertRoutingJobs>();

        // learn: 1. Declare a Slack channel with its URL from configuration
        // Built-in Slack incoming-webhook transport, with the webhook URL from configuration
        // (Alerts:SlackWebhookUrl). Without one the channel logs instead, so a plain run sends nothing.
        // Acta SQL stores only channel_name = "ops-slack" either way.
        // MinSeverity = Warning suppresses lower-severity alerts at delivery.
        var webhookUrl = builder.Configuration["Alerts:SlackWebhookUrl"];
        w.AddAlertChannel(
            "ops-slack",
            webhookUrl is null ? AlertTransportKinds.Log : AlertTransportKinds.SlackWebhook,
            endpoint: webhookUrl ?? "ops-slack",
            o =>
            {
                o.MinSeverity = AlertSeverityCode.Warning;
            }
        );
        // learn: end
    });
});

using var host = builder.Build();
await host.StartAsync();

var jobs = host.Services.GetRequiredService<IJobs>();

// The shared deduplicationKey collapses both reports onto a single alert row (OccurrenceCount = 2).
await jobs.EnqueueAsync(new QueueDepthCheck("orders", Depth: 12_000));
await jobs.EnqueueAsync(new QueueDepthCheck("orders", Depth: 13_500));
await Task.Delay(1000);

var queries = host.Services.GetRequiredService<IActaOperations>();
var alerts = await queries.Alerts.ListAsync(new ListAlertsQuery(JobNamespace: "real-alert-routing"));
foreach (var alert in alerts.Items)
{
    Console.WriteLine(
        $"alert [{alert.Severity}] {alert.Title} -> '{alert.ChannelName}' x{alert.OccurrenceCount}, delivery {alert.DeliveryStatus}"
    );
}

await host.StopAsync();

namespace Acta.Learn.RealAlertRouting
{
    public sealed record QueueDepthCheck(string Queue, int Depth);

    public sealed class QueueDepthCheckJob
    {
        [Job("queue-depth-check")]
        public async Task Handle(QueueDepthCheck input, JobContext context, CancellationToken ct)
        {
            await Task.Delay(50, ct);

            if (input.Depth > 10_000)
            {
                // learn: 2. Raise the alerts of one incident under one key
                // deduplicationKey ties repeats together onto one open incident row. The program enqueues two
                // checks of the same queue: both raise under one key and fold into one alert that counts two.
                await context.AlertAsync(
                    title: $"Queue backlog: {input.Queue}",
                    message: $"'{input.Queue}' depth is {input.Depth}, above the 10k threshold.",
                    severityCode: AlertSeverityCode.Error,
                    channelName: "ops-slack",
                    deduplicationKey: $"queue-depth:{input.Queue}",
                    ct: ct
                );
                // learn: end
                Console.WriteLine($"[{input.Queue}] depth {input.Depth} - alerted ops-slack");
                return;
            }

            Console.WriteLine($"[{input.Queue}] depth {input.Depth} OK");
        }
    }
}

Where to go next

New to Acta?

Acta is durable execution for .NET: workflows and jobs that survive restarts, as a library inside your application with its durable state in your SQL database.