JankStats
public final 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 |
|---|
public fun interface JankStats.OnFrameListenerThis interface should be implemented to receive per-frame callbacks with jank data. |
Public methods |
|
|---|---|
static final @NonNull JankStats |
@UiThreadCreates a new JankStats object and starts tracking jank metrics for the given window. |
final float |
This multiplier is used to determine when frames are exhibiting jank. |
final boolean |
Whether this JankStats instance is enabled for tracking and reporting jank data. |
final void |
setJankHeuristicMultiplier(float jankHeuristicMultiplier)This multiplier is used to determine when frames are exhibiting jank. |
final void |
@UiThreadEnabling 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. |
Public methods
createAndTrack
@UiThread
public static final @NonNull JankStats createAndTrack(
@NonNull Window window,
@NonNull JankStats.OnFrameListener frameListener
)
Creates a new JankStats object and starts tracking jank metrics for the given window.
| Throws | |
|---|---|
java.lang.IllegalStateException |
|
| See also | |
|---|---|
isTrackingEnabled |
getJankHeuristicMultiplier
public final float getJankHeuristicMultiplier()
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.
isTrackingEnabled
public final boolean isTrackingEnabled()
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.
setJankHeuristicMultiplier
public final void setJankHeuristicMultiplier(float jankHeuristicMultiplier)
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.
setTrackingEnabled
@UiThread
public final void setTrackingEnabled(boolean isTrackingEnabled)
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.