Acta. Durable execution for .NET

learn actawatch and control running work

How to choose how many events a job records

EventRecording on the job decides which events it writes. Audit, the default, records every event. Failures records the failed and orphaned attempts, the success that recovers from a failure, what an enabled alert profile reads, a caller's controls of the job, and a schedule's pauses and manual triggers.

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/407-event-recording
Read as

1Record only failures for a job that runs often

Failures: a failure writes an event, and so does the success that answers one; a run that succeeds after no failure leaves none. Use it for high-frequency definitions to keep events lean. The program also runs audit-work at the default level and counts the events of both.

event-recording.csexcerpt
public static class FailuresWorkJob
{
    [Job("failures-work", EventRecording = EventRecordingCode.Failures)]
    public static void Handle(FailuresWork input) => Console.WriteLine($"[{input.Id}] running at Failures level");
}

2Run 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/407-event-recording
Its output must contain
Audit level  -> event count: 1
Failures level -> event count: 0

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/407-event-recording, 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.

event-recording.cs63 lines
event-recording.cs
// How to choose how many events a job records
// `EventRecording` on the job decides which events it writes. `Audit`, the default, records every event. `Failures`
// records the failed and orphaned attempts, the success that recovers from a failure, what an enabled alert profile
// reads, a caller's controls of the job, and a schedule's pauses and manual triggers.
using Acta;
using Acta.Learn.EventRecording;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.UseActa(j =>
{
    j.UseLocalDatabase(builder.Configuration);
    j.Run<EventRecordingJobs>("event-recording");
});

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

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

// Audit: emits an attempt event (job.execution-succeeded, -failed, ...) for every run.
var auditOutcome = await jobs.EnqueueAsync(new AuditWork("report-a"));
await Task.Delay(500);
var auditEvents = await queries.Ledger.ListEventsAsync(new ListEventsQuery(Job: auditOutcome));
Console.WriteLine($"Audit level  -> event count: {auditEvents.Items.Count}");

// Failures: suppresses job.execution-succeeded for successful runs that follow no failure; failures emit.
var failuresOutcome = await jobs.EnqueueAsync(new FailuresWork("report-b"));
await Task.Delay(500);
var failuresEvents = await queries.Ledger.ListEventsAsync(new ListEventsQuery(Job: failuresOutcome));
Console.WriteLine(
    $"Failures level -> event count: {failuresEvents.Items.Count} (expected 0: a successful run emits nothing at Failures level)"
);

await host.StopAsync();

namespace Acta.Learn.EventRecording
{
    public sealed record AuditWork(string Id);

    public sealed record FailuresWork(string Id);

    public static class AuditWorkJob
    {
        // Audit (default): a finished event is written for every execution.
        [Job("audit-work", EventRecording = EventRecordingCode.Audit)]
        public static void Handle(AuditWork input) => Console.WriteLine($"[{input.Id}] running at Audit level");
    }

    public static class FailuresWorkJob
    {
        // learn: Record only failures for a job that runs often
        // Failures: a failure writes an event, and so does the success that answers one; a run that
        // succeeds after no failure leaves none. Use it for high-frequency definitions to keep events lean.
        // The program also runs `audit-work` at the default level and counts the events of both.
        [Job("failures-work", EventRecording = EventRecordingCode.Failures)]
        // learn: end
        public static void Handle(FailuresWork input) => Console.WriteLine($"[{input.Id}] running at Failures level");
    }
}

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.