Skip to content

Lineage

The lineage API answers "where did this come from, and what did it lead to?" for any unit of work. It follows the links described in Correlation, Tracing and the event sourcing design in both directions, so a user does not have to hop between the event, ledger, trace, workflow run, task and usage pages.

The implementation is LineageService (app/src/main/java/io/apitomy/axiom/app/LineageService.java), exposed by LineageResourceImpl. The UI component is LineagePanel (ui/src/components/LineagePanel.tsx).

API

GET /api/v1/lineage/{entityType}/{id}?direction=both&depth=5&maxNodes=200
Parameter Values Default
entityType event, trace, workflow-run, task —
id UUID for event and trace, a number otherwise —
direction upstream (origin), downstream (results) or both both
depth Hops walked in each direction, 1–10 5
maxNodes Maximum number of nodes, 1–1000 200

An unknown entity type, a malformed ID or an out-of-range or non-numeric parameter returns 400. A root that does not exist returns 404. Both carry the JSON Error body (message, errorCode). A non-numeric depth or maxNodes fails JAX-RS parameter conversion, which JAX-RS reports as 404; LineageResourceImpl declares a @ServerExceptionMapper for NotFoundException that turns it into 400. The mapper is declared on the resource class, so it applies to this resource only.

Subjects are not a root type: a subject holds too much unrelated work to give a useful graph.

The response is a LineageGraph:

Field Meaning
root Key of the root node
nodes LineageNode list
edges LineageEdge list
truncated true when the depth or node limit cut the walk short
depth, maxNodes The limits that were applied
totalCostUsd Sum of the nodes' costUsd

Each LineageNode has a key (type:id, used by edges), type, id, label, status, subtype (trace type, action type, trigger or outcome item type), linkPath (UI route), costUsd, direction (root, upstream or downstream), depth (hops from the root), available and createdOn.

Node types are the four root types plus outcome: a routing outcome item that is not a task or a workflow run (for example no-match).

Each LineageEdge has from, to and relation. Edges always point downstream, from the cause to the result, whichever direction was walked:

Relation From → to
triggered event → trace, event → workflow run
created trace / workflow run / task → task
resumed event → workflow run it resumed
produced trace or event → outcome item (e.g. no-match)
part-of owning workflow run → its trace (only when a trace is the root)
Type linkPath
event /events/stream/{id}
trace /logs/traces/{id}
workflow-run /runs/{id}
task /logs/tasks?taskId={id}
outcome none

Tasks have no detail page; the Tasks page opens a lineage modal for ?taskId=.

Traces and Their Owners

Workflow runs own their trace (workflow trace type). Such a trace is shown as its owner, not as a separate node, so a run and its trace never appear twice. Traces of any other type are trace nodes. If an owned trace's owner was deleted, the trace itself is shown.

When an owned trace is the root (GET /lineage/trace/{id}), the trace stays the root and its owner is linked upstream with part-of.

Traversal Rules

Upstream (origin)

Each node has at most one origin, except workflow runs, which can also have resume events.

Node Origin
task First that applies: workflowRunId → workflow run; the parent of the task's task trace node is another task's node → that task; traceId → trace or its owner; eventId → event
trace Owned: its owner (part-of). Otherwise eventId → event
workflow run trigger_event_id → event (triggered); each workflow_run_resume.event_id → event (resumed)
event none

trigger_event_id is set for every run started from an event: by a create-workflow routing rule, manually from the event detail page, or as a re-run of a run that was started from an event. Manual runs from an event have no ledger entry or routing outcome, so they are linked only through trigger_event_id. A re-run is not linked to the run it repeats; that link exists only as the run's rerunOf:<runId> label.

Downstream (results)

Node Results
event traces with eventId (owned ones as their owner); workflow runs with trigger_event_id; runs resumed by the event; routing_outcome_item rows reached through event_processing_ledger → routing_outcome: workflow-run and workflow-resumed items link the run; items of outcomes without a trace link a task or an outcome node
trace the work in the trace (below); items of routing_outcome rows with this trace_id (tasks and outcome nodes)
workflow run tasks with workflow_run_id; the work in its trace
task tasks whose task trace node is a child of this task's node (created by its agent)

"The work in a trace" is every task with that trace_id. A task whose trace node is a child of another task's node is linked to that task instead of to the trace owner.

Nodes reached from more than one place are included once, with every edge. With direction=both the upstream walk runs first, so a node found by both walks keeps upstream.

Limits and Truncation

The walk is breadth-first. depth limits the hops in each direction.

  • maxNodes also bounds the rows read: every expansion query (tasks of a trace or run, traces of an event, outcome items, resumes, child tasks) uses setMaxResults with the room left in the graph plus one. When a query returns that many rows, truncated is set. This is conservative: truncated can be true when the extra row was a node that was already in the graph.
  • Every IN list is split into chunks of at most 500 IDs (LineageService.IN_CHUNK).
  • A node is added only when the other end of its edge is already in the graph, so a truncated graph has no unconnected nodes. When a new node would exceed maxNodes, it is skipped and truncated is set; edges to skipped nodes are left out, so every edge refers to a node in the response.
  • When the depth limit is reached, the last level is expanded once more: edges between nodes that are already in the graph are kept, and truncated is set if any neighbour lies beyond the limit.

Cost

costUsd is the direct AI cost of a node, so costs can be added up without counting anything twice:

Node Sum of ai_usage.cost_usd where
task task_id = the task
trace, workflow run trace_id = the (run's) trace and task_id is null
event, outcome no cost

Query Batching (No N+1)

Every level of the walk does a fixed number of queries per node type, using IN (...) lists:

  1. Load the frontier: one query per type (stream_event, trace, workflow_run, task, routing_outcome_item). Events, tasks and workflow runs are read as projections of the label and link columns only, so event payloads, task input, output and logs, and workflow instance state are never loaded.
  2. Resolve trace owners: one query per owned trace type present.
  3. Expand: for example, for events one query each for traces, workflow runs, resumes, ledger rows, outcomes and items; for traces and owners one query each for tasks, the tasks' trace nodes and their parent nodes.

Entities found while expanding are cached, so they are not loaded again in the next level. Costs are computed once at the end with one grouped query per cost key (task, trace). The number of queries therefore depends on the depth and the node types, not on the number of nodes. LineageTest checks this with Hibernate statistics (%test.quarkus.hibernate-orm.statistics=true): a graph with 2 tasks and one with 12 tasks must use the same number of statements. It also checks that no StreamEventEntity, TaskEntity, or WorkflowRunEntity is loaded as an entity (entity load count 0), and that a trace with 30 tasks and maxNodes=5 reads at most 6 task rows (query execution row count).

Dangling References

All the links are soft references, and retention deletes events, traces and runs independently (see Data Retention). A reference to a missing row becomes a node with available: false, status: "unavailable", a label such as Event 3f2a... (deleted or unavailable) and no linkPath. The walk does not continue from such a node. Only a missing root returns 404.

UI

LineagePanel takes an entityType and id. It has Show origin (direction=upstream) and Show results (direction=downstream) views, rendered as an indented tree from the root with a link, status and cost on each node. Nothing is fetched until the panel is opened, and each view is fetched once. A node reached twice is expanded only the first time.

Page Placement
Event detail Expandable Lineage section below the tabs
Workflow run detail Lineage tab
Logs > Tasks, subject Tasks tab Lineage button, opens LineageModal