Own spans, facts and masks
The fold that orders the framework's spans takes yours too, in the same tree — a retrieval you run by hand, an evaluation score, a fact about the run — and every payload passes through your mask first. From code the run calls (a node, a tool), reach the run without passing it down → The run from inside.
import uuid
from etrack.models.event import EventKind
from etrack.ports.source import Edge
def mask(payload: dict) -> dict:
return {key: "***" if key == "input" else value for key, value in payload.items()}
tracker = Tracker(EventChannel(bus), LanggraphSourceAdapter(), redact=mask)
with tracker.track(thread="t1", config={"metadata": {"app.tenant": "acme"}}) as run:
await app.ainvoke({"question": "the answer", "answer": ""}, run.config)
# a span around your code
with run.fold.span("rerank", kind=EventKind.RETRIEVAL, payload={"k": 5}):
...
# a fact: born closed
run.fold.instant(
Edge(
id=uuid.uuid7().hex,
kind=EventKind.EVALUATION,
name="faithfulness",
payload={"score": 0.92},
)
)
Every frame, with its payload:
0 start run LangGraph {'input': '***'}
1 start node plan {}
2 end node plan {'keys': ['answer']}
3 start node answer {}
4 end node answer {'keys': ['answer']}
5 end run LangGraph {'keys': ['answer', 'question']}
6 start retrieval rerank {'k': 5}
7 end retrieval rerank {}
8 instant evaluation faithfulness {'score': 0.92}
redactmasked the run's input before any sink saw it.run.fold.span(...)opened and closed a span around the block —errorinstead ofendif the block raises, the exception re-raised. It yields the span's id, to nest further spans under it (parent=).run.fold.instant(...)recorded a fact under the run's root.- The
app.tenantmetadata landed on the root span'sattributes({'app.tenant': 'acme'}): put a run's own facts — agent version, tenant, experiment arm — underapp.and every backend sees them. A node's state outputs are reported by their keys, not their values: what a span carried in full is the model's and the tools' payloads.
A mask per sink
Tracker(redact=…) masks what every sink receives. To let one sink receive clear text while the others never do, give
the tracker no mask and each subscription its own:
bus.subscribe(otlp, redact=mask) # traces: masked
bus.subscribe(memory) # your memory service: the words as said
A subscription's mask covers the payload and the run's declared words, on that sink's own worker.
Extras — anything else, as structlog takes it
The record has its fields; anything else you hand it travels too, in attributes, to every sink — OTLP as span
attributes, the HTTP driver in its body, the forwarded log line flat:
import structlog
# around a whole run: every frame of it, the framework's included
with structlog.contextvars.bound_contextvars(tenant="acme", plan="pro"), tracker.track("t1", config) as run:
...
# on one span of your own
with run.fold.span("rerank", kind=EventKind.RETRIEVAL, k=5, index="policies"):
...
# on one frame you emit
channel.log.info("run.event", run_id=run_id, seq=7, id=span, kind="custom", phase="instant", score=0.92)
A key the model declares is a field, never an extra; explicit attributes win over a bound key of the same name; a
subclass of the record (→ The record) turns an extra into a typed field.
Strict mode. EventChannel(bus, strict=True) takes no extras: a key the model does not declare is refused with
ChannelError, and bound keys stay off the record — for a pipeline whose consumers expect the schema and nothing else.
Emit without a framework
Anything that is not a framework can emit straight into the channel — the same validation, the same sinks:
channel.log.info(
"run.event",
run_id=run_id, seq=0, id=span, kind="custom", phase="instant", name="deploy",
)
# a RunEvent you built yourself
channel.emit(event)
A frame missing a required field raises ChannelError naming it.
run.fold
span(name, kind=EventKind.CUSTOM, parent="", payload=None) |
context manager: start on entry, end on exit, error if the block raises (re-raised); yields the span id |
instant(Edge(...)) |
one frame born closed, under edge.parent or the run's root |
root |
the run's root span id |
scope |
the run's ids |
Edge (from etrack.ports.source): id, parent, kind, name, payload, attributes — and the graph
coordinates when you have them (node, ns, step).