PerformanceMetricsState

public final class PerformanceMetricsState

This class is used to store information about the state of an application that can be retrieved later to associate state with performance timing data.

For example, PerformanceMetricsState is used in conjunction with JankStats to enable JankStats to report per-frame performance characteristics along with the application state that was present at the time that the frame data was logged.

There is only one PerformanceMetricsState available per view hierarchy. That instance can be retrieved from the holder returned by PerformanceMetricsState.getHolderForHierarchy. Limiting PerformanceMetricsState to a single object per hierarchy makes it possible for code outside the core application logic, such as in a library, to store application state that can be useful for the application to know about.

Summary

Nested types

This class holds the current PerformanceMetricsState for a given view hierarchy.

Public methods
static final @NonNull PerformanceMetricsState.Holder

This function gets the single PerformanceMetricsState.Holder object for the view hierarchy in which `view' exists.
final void

putSingleFrameState is like putState, except the state persists only for the current frame and will be automatically removed after it is logged for that frame.
final void

Adds information about the state of the application that may be useful in future JankStats report logs.
final void

Removes information about a specified state.

Public methods

getHolderForHierarchy

Added in 1.0.0-beta01
@UiThread
public static final @NonNull PerformanceMetricsState.Holder getHolderForHierarchy(@NonNull View view)

This function gets the single PerformanceMetricsState.Holder object for the view hierarchy in which `view' exists. If there is no such object yet, this function will create and store one.

Note that the function will not create a PerformanceMetricsState object if the Holder's state is null; that object is created when a JankStats object is created. This is done to avoid recording performance state if it is not being tracked.

Note also that this function should only be called with a view that is added to the view hierarchy, since information about the holder is cached at the root of that hierarchy. The recommended approach is to set up the holder in View.OnAttachStateChangeListener.onViewAttachedToWindow.

putSingleFrameState

Added in 1.0.0-beta01
public final void putSingleFrameState(@NonNull String key, @NonNull String value)

putSingleFrameState is like putState, except the state persists only for the current frame and will be automatically removed after it is logged for that frame.

This method can be used for very short-lived state, or state for which it may be difficult to determine when it should be removed (leading to erroneous data if state is left present long after it actually stopped happening in the app).

Parameters
@NonNull String key

An arbitrary name used for this state, used as a key for storing the state value.
@NonNull String value

The value of this state.
See also
putState

putState

Added in 1.0.0-beta01
public final void putState(@NonNull String key, @NonNull String value)

Adds information about the state of the application that may be useful in future JankStats report logs.

State information can be about UI elements that are currently active (such as the current Activity or layout) or a user interaction like flinging a list. If the PerformanceMetricsState object already contains an entry with the same key, the old value is replaced by the new one. Note that this means apps with several instances of similar objects (such as multipe RecyclerViews) should therefore use unique keys for these instances to avoid clobbering state values for other instances and to provide enough information for later analysis which allows for disambiguation between these objects. For example, using "RVHeaders" and "RVContent" might be more helpful than just "RecyclerView" for a messaging app using RecyclerView objects for both a headers list and a list of message contents.

Some state may be provided automatically by other AndroidX libraries. But applications are encouraged to add user state specific to those applications to provide more context and more actionable information in JankStats logs.

For example, an app that wanted to track jank data about a specific transition in a picture-gallery view might provide state like this:

state.putState("GalleryTransition", "Running")

Parameters
@NonNull String key

An arbitrary name used for this state, used as a key for storing the state value.
@NonNull String value

The value of this state.
See also
removeState

removeState

Added in 1.0.0-beta01
public final void removeState(@NonNull String key)

Removes information about a specified state.

removeState is typically called when the user stops being in that state, such as leaving a container previously put in the state, or stopping some interaction that was similarly saved.

Parameters
@NonNull String key

The name used for this state, should match the name used when putting the state previously.
See also
putState