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
| 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) |
Link paths
| 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.
maxNodesalso bounds the rows read: every expansion query (tasks of a trace or run, traces of an event, outcome items, resumes, child tasks) usessetMaxResultswith the room left in the graph plus one. When a query returns that many rows,truncatedis set. This is conservative:truncatedcan betruewhen the extra row was a node that was already in the graph.- Every
INlist 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 andtruncatedis 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
truncatedis 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:
- 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. - Resolve trace owners: one query per owned trace type present.
- 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 |