Start
Lilium
Concepts

Traces and spans

The Lilium data model: how runs, spans, and lineage relate, and what each span carries.

Updated August 4, 2026

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.

KindRepresents
agentA logical agent or sub-agent boundary
modelA single model request
toolA tool or function invocation
retrievalA search or vector lookup
spanApplication 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.