Skip to content

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.

root property

root: str

The id of the run's root span, empty until the first kept span opens.

scope property

scope: RunScope

The run this fold stamps.

annotate

annotate(**attributes: Any) -> None

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

declare(
    input: str | None = None, output: str | None = None
) -> None

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.