Skip to content

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

dedupe_key: str

What makes a frame unique across redeliveries: its run, its span and the edge of the span it marks.

trace_id property

trace_id: str

The W3C trace id of the run: the run id itself, so every tracer names the run the same way.

masked

masked(redact: Redact) -> Self

The frame as a mask lets it through: its payload, and the run's declared words, each passed through redact; a declared word the mask drops is gone.

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.

ended property

ended: bool

Whether this frame closes the run: its root's END or ERROR.

Usage

Bases: Struct

Tokens a model call spent, by kind, and its cost when known; on a NODE's or a RUN's END, the total of every model call that ran under it.

__add__

__add__(other: Usage) -> Usage

Two spends as one: every count summed, the cost summed over what is known — unknown when neither is.