Skip to content

Custom sinks and policies

A sink is any class with three declarations and one method. The bus narrows each event to what the sink reads, skips the phases it does not want before queueing, and delivers on the sink's own worker.

The bus: policies and losses

subscribe(sink, select=None) serve a sink from now on — before or after the bus opens; select sees each event first and returns it, a transformed copy, or None to skip it, on the sink's own worker
publish(event) returns at once, from any thread; the channel calls it, you normally don't
dropped, failed events lost per sink because its queue was full; deliveries that raised

Setting: ETRACK_BUS_CAPACITY (1000) — events queued per sink. Past it, a slow sink loses the newest and the loss is counted, never the run's problem. A synchronous burst longer than the capacity, with no await in between, drops the rest: give the loop a turn in long synchronous loops.

Write a sink

Three class attributes and one method, plus the lifecycle every provider has:

from typing import ClassVar

from etrack.models.event import EventPhase, EventView
from etrack.ports.provider import Isolation, Locality, ProviderSpec, Workload


class CostSink:
    """Every LLM call's tokens, summed per run."""

    spec: ClassVar[ProviderSpec] = ProviderSpec(
        "cost", Locality.EMBEDDED, Workload.IO_BOUND, Isolation.LOOP
    )
    # the fields it reads (→ The record · Views)
    view: ClassVar[type[EventView]] = Cost
    # the phases it wants: no deltas, ever
    phases: ClassVar[frozenset[EventPhase]] = frozenset({EventPhase.END})

    def __init__(self) -> None:
        self.tokens: dict[str, int] = {}

    async def __aenter__(self): return self
    async def __aexit__(self, *exc): ...
    async def health(self) -> bool: return True

    async def send(self, view: Cost) -> None:
        if view.kind == "llm" and view.usage:
            spent = view.usage.total_tokens
            self.tokens[view.run_id] = self.tokens.get(view.run_id, 0) + spent
Declares Effect
spec its name in bus.dropped / bus.failed and in the logs
view the bus narrows each event onto it before send
phases the bus skips the other phases before queueing: a sink that ignores token deltas never pays for them
send the one delivery call; raising is counted in bus.failed and logged, the next event still arrives

LiveAdapter — the live buffer

Keeps the last frames of every conversation in memory and pushes new ones to whoever watches: what the viewer, a chat UI or a reconnecting client read.

from etrack.providers.adapters.sink.live import LiveAdapter

async with LiveAdapter() as live:
    bus.subscribe(live)
    ...
    # frames 42… kept, then every new one, live
    async for frame in live.watch("t1", after=41):
        print(frame.offset, frame.event.kind, frame.event.name)
    # the kept conversations, newest first
    live.threads()
watch(thread, after=-1) replay what is kept past after, then follow; a client that reconnects with the last offset it saw misses nothing still kept
threads() every kept thread: next offset, its runs, its last frame's time — newest first
offset(thread) how many frames the thread has had

offset is per thread and contiguous across runs, unlike seq, which restarts each run.

setting default
ETRACK_LIVE_BUFFER 2000 frames kept per thread for a reconnect to replay
ETRACK_LIVE_THREADS 256 threads kept; the least recently written is evicted first
ETRACK_LIVE_BACKLOG 1000 frames a watcher may lag before it is cut off, rather than slow the bus