Traces and spans
The Lilium data model: how runs, spans, and lineage relate, and what each span carries.
Everything in Lilium is built on one structure. Understanding it makes the rest of the product predictable.
#Runs
A run is one unit of agent work: a request, a job, a scheduled task. It is what an operator reviews when something goes wrong, and it is the level at which cost, latency, and outcome are reported.
A run is represented by a root span. Creating one is a single call, and everything instrumented inside inherits it.
#Spans
A span is one operation inside a run. Every span carries a name, a kind, start and end timestamps, a parent reference, and a status.
| Kind | Represents |
|---|---|
agent | A logical agent or sub-agent boundary |
model | A single model request |
tool | A tool or function invocation |
retrieval | A search or vector lookup |
span | Application work that does not fit the above |
Model spans additionally carry provider, model, token usage, and computed cost. Tool spans carry serialized inputs and outputs, subject to redaction.
#Lineage
Lineage is the parent and child relationship between spans, preserved across sub-agents, retries, and async boundaries. It is what separates a trace from a log stream.
Lineage is what makes three common questions answerable:
- Which decision selected the tool that failed?
- Did this retry use different arguments than the original attempt?
- Which branch of a fan-out produced the output the user actually saw?
#Attributes and metadata
Attributes are set by the SDK. Metadata is set by you, and becomes a filter dimension across dashboards and search. Choose fields you will want to slice by later: tenant, plan, prompt version, surface, and outcome are all more useful than a free-text note.
#Payloads
Payloads are the prompts, completions, and tool arguments attached to a span. They are optional, redacted before they leave your process, and are what makes replay possible. A trace without payloads still shows structure and cost; it cannot be replayed faithfully.