Skip to content

docs: add render telemetry guide - #59

Merged
chiefcll merged 1 commit into
mainfrom
docs/render-telemetry
Sep 9, 2026
Merged

chiefcll merged 1 commit into
mainfrom
docs/render-telemetry

Conversation

@chiefcll

@chiefcll chiefcll commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

Adds docs/articles/telemetry.md, a guide for apps that want production render telemetry, plus a sidebar entry under Advanced Topics.

Why

The renderer's fpsUpdate payload has 25+ fields and several pooling traps (sampledFrames vs renderedFrames, weighting meanActiveAnimations, pooling rates instead of sum(frames) / sum(ms)). Apps wiring it into a dashboard end up reimplementing all of that. For a fleet dashboard, two numbers answer the question "is this viewer having a good time":

Field Question
PAGE_SETTLE_MS How long from a route change until the new page was fully drawn, images included.
ANIMATED_FPS How smooth motion was while something was moving.

What the page covers

  • idle is the boundary for both metrics. It fires once per active-to-idle transition, and the stage stays non-idle while textures are queued, so the first idle after a route change is the moment the new page's node burst is on screen with its images uploaded. No component instrumentation and no timers.
  • animatedFps rather than fps, since a screen that draws one frame for a late texture then sits still posts a rate no viewer perceived.
  • Setup (fpsUpdateInterval, setTelemetrySegment, keeping segment labels low cardinality), a dependency-free tracker with an emit callback, and router wiring via useLocation.
  • Which aggregate to watch per field, and the explicit handoff: when a number goes red, reproduce on device and profile there. That is why the phase fields (updateMs / renderMs / uploadMs) are deliberately not in the reported set.
  • The gaps, stated plainly: a permanently animating screen never goes idle so it reports no settle time, the DOM renderer emits neither event, and pre-1.8 series are not comparable.

Docs only, no source changes.

🤖 Generated with Claude Code

Reduces the renderer's fpsUpdate payload to two production metrics: page
settle time, taken from the first `idle` after a route change, and pooled
animated FPS for the burst that just ended.

Covers why `idle` is the right boundary (the stage stays non-idle while
textures are queued, so the first one after a navigation is the new page
fully drawn), why `animatedFps` rather than `fps`, a dependency-free
tracker, router wiring, and the gaps (a permanently animating screen never
reports a settle time, the DOM renderer emits neither event).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@chiefcll
chiefcll merged commit 6dfecfb into main Sep 9, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant