event
etrack.models.event
models/event: RunEvent — the one record every source writes and every client reads, and the views that narrow it.
A run is a tree of spans. A frame names its span (id) and its visible parent, so any client rebuilds the tree
without knowing the framework that produced it; seq orders the frames of one run. The two axes say what happened:
kind is what the span is (aligned with OpenTelemetry's GenAI operations and AG-UI's agent concepts), phase where
it is in its life; part says what a streamed piece carries (text, reasoning, a tool call's arguments, media).
The field names are the reserved keys of the log channel. The record grows two ways and never breaks: optional typed
sections (model, usage, error) and the open attributes bag, namespaced by its consumer (agui.*, app.*); a
project that needs more subclasses RunEvent and hands the subclass to the channel. A client never reads the record
whole: it declares an EventView with the fields it needs and project narrows any event onto it.
EventKind
Bases: StrEnum
What a span is. CUSTOM is the fallback for whatever a source or a project names that no other kind covers.
EventPhase
Bases: StrEnum
Where a span is in its life; INSTANT is a span that is born and closed at once (an interrupt, a state, a score).
EventView
Bases: Struct
The base of every view a client declares: a subset of the record's fields, same names, same types.
project
classmethod
project(event: EventView) -> Self
Any event narrowed onto this view — fields this view does not declare are left behind.
Failure
Bases: Struct
Why a span failed: the exception's type and its message.
LogView
Bases: EventView
What a log line keeps of a frame: the coordinates and the measures, never the payload.
ModelRef
Bases: Struct
Which model served a call: the provider, the model's name, and the request parameters worth keeping.
Outcome
Bases: StrEnum
How a run ended: it ran to its end, it stopped to ask (an interrupt, resumed by a later run), or it failed.
Part
Bases: StrEnum
What a streamed piece carries — LangChain's v1 content blocks, AG-UI's message kinds; CUSTOM for the rest.
RunEvent
Bases: EventView
One frame of a run: who, where in the tree, what and when, and what it carried.
node, ns and step are the graph coordinates when the source has a graph (the node a span runs under, its
subgraph path, the superstep); visit counts how many times the run has entered that node. message_id and
call_id tie a frame to the chat message or the tool call a client renders. latency_ms is set on END and ERROR.
The run's root closes with what the run declared — input, what entered, and output, what it published, each set
by the code that said it (run.declare), never inferred — and its outcome; no declaration, no field.
dedupe_key
property
What makes a frame unique across redeliveries: its run, its span and the edge of the span it marks.
trace_id
property
The W3C trace id of the run: the run id itself, so every tracer names the run the same way.
RunScope
Bases: Struct
One run before its first frame: its id (32 hex, the trace id too) and the conversation it belongs to.
RunView
Bases: EventView
A run as its root closes it: whose, when, how long, what it took in and published, how it ended, what it carries.
What a run-level consumer reads — one item per run, written when ended — with the host's attributes lifted onto
the root (app.*) and the ones annotated on the way.