docs: add render telemetry guide - #59
Merged
Merged
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
fpsUpdatepayload has 25+ fields and several pooling traps (sampledFramesvsrenderedFrames, weightingmeanActiveAnimations, pooling rates instead ofsum(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":PAGE_SETTLE_MSANIMATED_FPSWhat the page covers
idleis 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 firstidleafter 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.animatedFpsrather thanfps, since a screen that draws one frame for a late texture then sits still posts a rate no viewer perceived.fpsUpdateInterval,setTelemetrySegment, keeping segment labels low cardinality), a dependency-free tracker with anemitcallback, and router wiring viauseLocation.updateMs/renderMs/uploadMs) are deliberately not in the reported set.Docs only, no source changes.
🤖 Generated with Claude Code