fold
etrack.processors.fold
processors/fold: FoldProcessor — a source's edges folded into ordered, parented, stamped RunEvents for one run.
A source reports every span it sees; the fold keeps the ones a person reads (an edge with a kind) and folds
plumbing (kind=None) into its nearest kept ancestor, so a frame's parent is always a span that was itself emitted.
It stamps what the source cannot know: the run's ids, seq, the visit count of each node, the latency of a closed
span, and the payload passed through the project's redact. The run's root closes with what the run declared (declare:
what entered, what it published), the attributes it was annotated with, and how it ended — failed, interrupted (an
interrupt was folded) or completed. With propagate, every frame carries the root's attributes (the host's app.*).
One fold per run; emit is whoever takes the frames.
FoldProcessor
FoldProcessor(
scope: RunScope,
emit: Emit,
redact: Redact | None = None,
*,
propagate: bool = False,
pricer: Pricer | None = None,
)
One run's edges as frames, pushed to emit the moment they are folded.
annotate
Attributes learnt during the run — a verdict, a cut, a consent read late —, carried by the run's END.
close
close(
span: str,
payload: dict[str, Any],
usage: Usage | None = None,
error: Failure | None = None,
) -> None
A span ends — END, or ERROR when it carries a failure; closing a folded or unknown span does nothing.
declare
What the run took in and what it published, as the code that said it states them; the root's END carries them. A word given again replaces the last; a word never given stays absent.
delta
delta(
span: str,
part: Part,
payload: dict[str, Any],
call_id: str = "",
) -> None
A streamed piece of an open span; a piece of a span never opened, or already closed, is dropped.
instant
instant(edge: Edge) -> None
A frame born closed — an interrupt, a state, a score, a custom fact — under its visible parent.
open
open(edge: Edge) -> None
A span begins: emitted when kept, folded into its ancestor when plumbing.
span
span(
name: str,
kind: EventKind = CUSTOM,
parent: str = "",
payload: dict[str, Any] | None = None,
**attributes: Any,
) -> Generator[str]
A span around a block of the project's own code: START on entry, END or ERROR on exit; yields its id. Any
other keyword is an attribute of the span — run.fold.span("rank", tenant="acme", k=5).
OpenSpan
dataclass
OpenSpan(
edge: Edge, parent: str, visit: int | None, began: float
)
A kept span still running: the edge it opened with, its visible parent, its visit and when it began.