Docs idea: telling "no jank found" apart from "no frames were collected" when profiling

[Ky0-Nguyen]

Summary

A small docs proposal, and optionally a short community blog post, about an easy-to-miss profiling mistake: a capture that contains no frame or CPU data still produces a clean-looking result. "No jank found" and "no frames were collected" read the same in a summary, but only the first one says anything about the app.

Motivation

I ran into this while profiling a small React Native CLI app:

• On a physical Pixel 9 (Android 16) in a device cloud, a ~25 s profile came back with counters only: 0 frame records and 0 CPU samples. Any summary built on top of it ("0 issues") is technically true and tells you nothing about jank.
• On a local Android emulator, a ~270 s live capture recorded thousands of memory-counter events and, again, no frames and no CPU samples.

In both cases nothing looked broken. The data simply was not there, and it is easy to read an empty track as a fast app. I suspect many people hit this without noticing, especially when a tool shows a green summary.

Proposal

1. Profiling guide (docs/profiling.md): add a short "Check the trace before you read it" note. Before drawing conclusions, confirm that the trace actually contains frames (for example Choreographer#doFrame on the UI thread and DrawFrame on the RenderThread in Android Studio or Perfetto) and CPU samples for your app's process during the interaction you care about. An empty track means not measured, not fast.
2. Optionally, a community blog post (~1,000 words), vendor-neutral and using only the tools the docs already recommend (Android Studio Profiler, Perfetto, Instruments): how to recognise an empty or partial capture, common reasons it happens, and why "not measured" should never be shown as zero.

Transparency

I maintain an open-source macOS profiler for React Native (DevX), which is where this came up. Neither the docs change nor the post would be about it; they would only reference the tools already used in the docs.

Questions

• Is the Profiling guide the right place for this note?
• Would the team consider a community post on the blog, or should this stay docs-only?

Happy to open the PR(s) if this sounds useful.

[SanketPathare]

This is a useful documentation improvement because “no jank found” and “no frames were collected” represent two different profiling outcomes.

I suggest making the distinction explicit in the profiling results:

• No jank found: Frames were successfully collected and analyzed, but none exceeded the configured jank threshold.
• No frames were collected: The profiler did not capture any frames, so there is not enough data to determine whether jank occurred.

It would also help to show a clear message when no frames are available, explaining possible reasons such as an inactive recording session, an unsupported profiling environment, or a recording that ended before any frames were captured.

This distinction prevents users from interpreting missing profiling data as proof that their application is performing smoothly.

A small UI example could be:

No jank detected in 245 frames.

versus:

No frames collected. Start a profiling session and try again.

The documentation should also clarify what counts as a valid frame and which threshold is used to classify jank.

[Ky0-Nguyen]

Thanks @SanketPathare, agreed. The definition point is the most useful one for the docs: what counts as a frame and which threshold applies, since the budget depends on the display’s refresh rate (16.7 ms at 60 Hz, 8.3 ms at 120 Hz). Profiler UI messages belong to each tool, so in the docs I’d turn your list of reasons into a short checklist to run before reading a trace. I’ll open a small PR against docs/profiling.md and link it here.