Public hook or event for live-query graph runs (for performance attribution)
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 3.9k
- Forks
- 266
- Avg merge
- 1d 4h
- Merged PRs (30d)
- 55
Description
Problem
We attribute main-thread long tasks to the sync stage that caused them using performance.mark pairs around our own collection commits (co:sync:commit:start/end). The other half of the picture, the time a commit spends re-running dependent live queries, has no public seam: CollectionConfigBuilder.executeGraphRun / maybeRunGraph run synchronously inside the source collection's commit and are private, and CollectionConfigBuilder is not re-exported from @tanstack/db.
What exists publicly today does not cover it:
createLiveQueryObserversubscribes to changes and status, not to the run itself.createEffect's per-graph-run callback fires per effect query, so instrumenting it does not coveruseLiveQuery/createLiveQueryCollectionsites (we have ~65).- Collection events are
status:change,subscribers:change,index:added,index:removed.
Patching the dist to wrap executeGraphRun works but is a vendor carry we do not want to maintain for a metric.
Request
A public, opt-in event around a live query's graph run, for example on the live query collection:
collection.on('graph:run', ({ id, durationMs, changes }) => { /* mark / measure */ })
or a global hook (onLiveQueryRun(listener)) that fires with { id, startTime, endTime } per executeGraphRun. Either lets consumers emit performance.mark pairs with detail: { collection: id } and lets DevTools-style tooling attribute long tasks to specific queries without touching internals.
Context
@tanstack/db 0.7.2. Related to the offset-regression issue we filed against electric-sql/electric#4806 in the same instrumentation effort.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing CollectionConfigBuilder.executeGraphRun and maybeRunGraph, then compare the proposed live-query collection event with the global onLiveQueryRun hook. Done means an opt-in public seam reports each graph run with timing and collection identity, covers useLiveQuery and createLiveQueryCollection, and avoids patching dist internals.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- observability, performance
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100