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.
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
// 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:
dotnet run --project learn/400-observability-and-alerts/404-read-event-timelineparent 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-yieldedandjob.suspended. A sleep writesjob.execution-yieldedandjob.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
// 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);
}
}
}