Operations

API

capture        ingest events
definitions    declare and manage event definitions and spans
recompute      re-materialise spans after a definition changes
query          trend and cohort-contrast aggregation

Declaring telemetry

Events are declared per application in telemetry.yaml and validated at load. Declaring them rather than emitting ad-hoc strings is what keeps the catalogue stable enough that a span defined months later still resolves — an undeclared event is dropped, not silently accepted.

Recompute

recompute is what makes retrospective spans work. Change a span definition and the block rebuilds its duration vectors from captured events, rather than applying the new definition only going forward.

Expect to run it after any definition change you care about historically. Without it you get a discontinuity in the trend at the moment of the change, which reads as a real change in the process rather than a change in measurement.

Storage

Data	Store	Why
Telemetry events	ClickHouse	High-volume, append-only, columnar aggregation
Definitions and spans	PostgreSQL	Low-volume, relational, transactional

The split follows the access pattern rather than preference. Event volume is the dimension that grows; definitions are small and change rarely.

Capacity

Capture volume scales with product usage, not with how many spans you have defined — spans are computed over events, so adding a span costs a recompute rather than more ingest.

That is the intended way to use it: capture broadly once, then define as many spans as questions you have.

What to watch

Signal	Why it matters
Idle share of a span	Usually the largest and most improvable component
AI share trend	Whether the loop is taking on more, or just being present
Unpaired span starts	Cases that begin and never end — often a real process failure
Capture volume vs catalogue	Undeclared events being dropped
Recompute lag after changes	Trends that look like process change but are measurement change

Unpaired span starts deserve attention. A span whose end event never arrives usually means the process genuinely stalled — the measurement is not broken, the process is, and this is often the first place that shows up.