PerformanceMetricsState

@UiThread
fun getHolderForHierarchy(view: View): PerformanceMetricsState.Holder

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.

fun putSingleFrameState(key: String, value: String): Unit

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).

fun putState(key: String, value: String): Unit

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")

fun removeState(key: String): Unit

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.