Acta. Durable execution for .NET

learn actawatch and control running work

How to read why a job did what it did

The append-only event ledger answers why a job did what it did. ListEventsAsync with LineageRoot reads the timeline of a job and of every child it started.

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/404-read-event-timeline
Read as

1Read the timeline of the job and its children

Query the full lineage event timeline scoped to the lineage root (the parent job). Events are returned newest-first; reverse to print in chronological order. The parent starts a collect child that fails with "data origin unavailable", which is the reason the timeline shows.

read-event-timeline.csexcerpt
Console.WriteLine($"parent finished with status: {finished.Status}");

Console.WriteLine("event timeline for the lineage:");

var eventsPage = await queries.Ledger.ListEventsAsync(new ListEventsQuery(LineageRoot: parent, PageSize: 100));
var events = eventsPage.Items.Reverse().ToList();
foreach (var e in events)
{
    var details = e.DetailsText is { } d ? $" {d}" : "";
    var msg = e.Message is { } m ? $" ({m})" : "";
    Console.WriteLine($"  [{e.JobRef}] {e.EventCode}{details}{msg}");
}

2The job it acts on

read-event-timeline.csexcerpt
// Parent starts a child that gathers data; the child fails deliberately to show a failure reason on the timeline.
[Job("run-report", MaxAttempts = 1)]
public static async Task HandleParent(RunReport input, JobContext context, CancellationToken ct)
{
    Console.WriteLine($"[run-report] starting data collection for {input.Period}");
    var collected = await context.CallChildAsync("collect", new CollectData(input.Period), ct);
    if (!collected.Succeeded)
    {
        await context.FailAsync($"data collection failed for {input.Period}", ct);
    }
}

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/404-read-event-timeline
Its output must contain
parent finished with status: Failed
(data collection failed for q4-2024)
(data origin unavailable)

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

Remember

  • A timeline starts at the first attempt. The enqueue is the job's row, CreatedAtUtc, not an event.
  • A wait writes two events at one instant: job.execution-yielded and job.suspended. A sleep writes job.execution-yielded and job.slept.
  • new ListEventsQuery(LineageRoot: root.JobRef) reads a whole tree's timeline in one query, children included.

The whole program

Every file of learn/400-observability-and-alerts/404-read-event-timeline, 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.

read-event-timeline.cs79 lines
read-event-timeline.cs
// How to read why a job did what it did
// The append-only event ledger answers why a job did what it did. `ListEventsAsync` with `LineageRoot` reads the
// timeline of a job and of every child it started.
using Acta;
using Acta.Learn.ReadEventTimeline;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.UseActa(j =>
{
    j.UseLocalDatabase(builder.Configuration);
    j.Run<ReadEventTimelineJobs>("read-event-timeline");
});

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

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

// Enqueue the parent; it will start a child that deliberately fails.
Console.WriteLine("enqueuing parent job...");
var parent = await jobs.EnqueueAsync(new RunReport("q4-2024"));

// Wait for the lineage to reach a terminal state.
Console.WriteLine("waiting for lineage to finish...");
var finished = await parent.WaitAsync();

Console.WriteLine($"parent finished with status: {finished.Status}");

Console.WriteLine("event timeline for the lineage:");

// learn: Read the timeline of the job and its children
// Query the full lineage event timeline scoped to the lineage root (the parent job).
// Events are returned newest-first; reverse to print in chronological order. The parent starts a `collect`
// child that fails with "data origin unavailable", which is the reason the timeline shows.
var eventsPage = await queries.Ledger.ListEventsAsync(new ListEventsQuery(LineageRoot: parent, PageSize: 100));
var events = eventsPage.Items.Reverse().ToList();

// learn: end
foreach (var e in events)
{
    var details = e.DetailsText is { } d ? $" {d}" : "";
    var msg = e.Message is { } m ? $" ({m})" : "";
    Console.WriteLine($"  [{e.JobRef}] {e.EventCode}{details}{msg}");
}

await host.StopAsync();

namespace Acta.Learn.ReadEventTimeline
{
    public sealed record RunReport(string Period);

    public sealed record CollectData(string Period);

    public static class ReportingJobs
    {
        // Parent starts a child that gathers data; the child fails deliberately to show a failure reason on the timeline.
        [Job("run-report", MaxAttempts = 1)]
        public static async Task HandleParent(RunReport input, JobContext context, CancellationToken ct)
        {
            Console.WriteLine($"[run-report] starting data collection for {input.Period}");
            var collected = await context.CallChildAsync("collect", new CollectData(input.Period), ct);
            if (!collected.Succeeded)
            {
                await context.FailAsync($"data collection failed for {input.Period}", ct);
            }
        }

        [Job("collect-data", MaxAttempts = 1)]
        public static Task HandleChild(CollectData input, JobContext context, CancellationToken ct)
        {
            Console.WriteLine($"[collect-data] data origin unavailable for {input.Period}");
            return context.FailAsync("data origin unavailable", ct);
        }
    }
}

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.