class JankStats

This class is used to both accumulate and report information about UI "jank" (runtime performance problems) in an application.

There are three major components at work in JankStats:

Identifying Jank: This library uses internal heuristics to determine when jank has occurred, and uses that information to know when to issue jank reports so that developers have information on those problems to help analyze and fix the issues.

Providing UI Context: To make the jank reports more useful and actionable, the system provides a mechanism to help track the current state of the UI and user. This information is provided whenever reports are logged, so that developers can understand not only when problems occurred, but what the user was doing at the time, to help identify problem areas in the application that can then be addressed. Some of this state is provided automatically, and internally, by various AndroidX libraries. But developers are encouraged to provide their own app-specific state as well. See PerformanceMetricsState for more information on logging this state information.

Reporting Results: On every frame, the JankStats client is notified via a listener with information about that frame, including how long the frame took to complete, whether it was considered jank, and what the UI context was during that frame. Clients are encouraged to aggregate and upload the data as they see fit for analysis that can help debug overall performance problems.

Note that the behavior of JankStats varies according to API level, because it is dependent upon underlying capabilities in the platform to determine frame timing information. Below API level 16, JankStats does nothing, because there is no way to derive dependable frame timing data. Starting at API level 16, JankStats uses rough frame timing information that can at least provide estimates of how long frames should have taken, compared to how long they actually took. Starting with API level 24, frame durations are more dependable, using platform timing APIs that are available in that release. And starting in API level 31, there is even more underlying platform information which helps provide more accurate timing still. On all of these releases (starting with API level 16), the base functionality of JankStats should at least provide useful information about performance problems, along with the state of the application during those frames, but the timing data will be necessarily more accurate for later releases, as described above.

Summary

Nested types

This interface should be implemented to receive per-frame callbacks with jank data.

Public companion functions
JankStats

Creates a new JankStats object and starts tracking jank metrics for the given window.

Public properties
Boolean

Whether this JankStats instance is enabled for tracking and reporting jank data.
Float

This multiplier is used to determine when frames are exhibiting jank.

Public companion functions

createAndTrack

Added in 1.0.0-beta01
@UiThread
fun createAndTrack(window: Window, frameListener: JankStats.OnFrameListener): JankStats

Creates a new JankStats object and starts tracking jank metrics for the given window.

Throws
java.lang.IllegalStateException

window must be active, with a non-null DecorView. See Window.peekDecorView.
See also
isTrackingEnabled

Public properties

isTrackingEnabled

Added in 1.0.0-beta01
var isTrackingEnabled: Boolean

Whether this JankStats instance is enabled for tracking and reporting jank data. Enabling tracking causes JankStats to listen to system frame-timing information and record data on a per-frame basis that can later be reported to the JankStats listener. Tracking is enabled by default at creation time.

jankHeuristicMultiplier

Added in 1.0.0-beta01
var jankHeuristicMultiplier: Float

This multiplier is used to determine when frames are exhibiting jank.

The factor is multiplied by the current refresh rate to calculate a frame duration beyond which frames are considered, and reported, as having jank. For example, an app wishing to ignore smaller-duration jank events should increase the multiplier. Setting the value to 0, while not recommended for production usage, causes all frames to be regarded as jank, which can be used in tests to verify correct instrumentation behavior.

By default, the multiplier is 2.