Added in API level 24

Summary: Methods | Inherited Methods

SystemHealthManager

---

Kotlin |Java

public class SystemHealthManager
extends Object

java.lang.Object
↳	android.os.health.SystemHealthManager

---

Provides access to data about how various system resources are used by applications.

Summary

Public methods
float	getCpuHeadroom(CpuHeadroomParams params) Provides an estimate of available CPU capacity headroom of the device.
Pair<Integer, Integer>	getCpuHeadroomCalculationWindowRange() Gets the range of the calculation window size for CPU headroom.
long	getCpuHeadroomMinIntervalMillis() Gets minimum polling interval for calling getCpuHeadroom(android.os.CpuHeadroomParams) in milliseconds.
float	getGpuHeadroom(GpuHeadroomParams params) Provides an estimate of available GPU capacity headroom of the device.
Pair<Integer, Integer>	getGpuHeadroomCalculationWindowRange() Gets the range of the calculation window size for GPU headroom.
long	getGpuHeadroomMinIntervalMillis() Gets minimum polling interval for calling getGpuHeadroom(android.os.GpuHeadroomParams) in milliseconds.
int	getMaxCpuHeadroomTidsSize() Gets the maximum number of TIDs this device supports for getting CPU headroom.
void	getPowerMonitorReadings(List<PowerMonitor> powerMonitors, Executor executor, OutcomeReceiver<PowerMonitorReadings, RuntimeException> onResult) Asynchronously retrieves the accumulated power consumption reported by the specified power monitors.
void	getSupportedPowerMonitors(Executor executor, Consumer<List<PowerMonitor>> onResult) Asynchronously retrieves a list of supported PowerMonitor's, which include raw ODPM (on-device power rail monitor) rails and modeled energy consumers.
HealthStats	takeMyUidSnapshot() Return a HealthStats object containing a snapshot of system health metrics for the application calling this API.
HealthStats	takeUidSnapshot(int uid) Return a HealthStats object containing a snapshot of system health metrics for the given uid (user-id, which in usually corresponds to application).
HealthStats[]	takeUidSnapshots(int[] uids) Return a HealthStats object containing a snapshot of system health metrics for the given uids (user-id, which in usually corresponds to application).

Inherited methods

From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Public methods

getCpuHeadroom

Added in Android Baklava

public float getCpuHeadroom (CpuHeadroomParams params)

Provides an estimate of available CPU capacity headroom of the device.

The value can be used by the calling application to determine if the workload was CPU bound and then take action accordingly to ensure that the workload can be completed smoothly. It can also be used with the thermal status and headroom to determine if reducing the CPU bound workload can help reduce the device temperature to avoid thermal throttling.

If the params are valid, each call will perform at least one synchronous binder transaction that can take more than 1ms. So it's not recommended to call or wait for this on critical threads. Some devices may implement this as an on-demand API with lazy initialization, so the caller should expect higher latency when making the first call (especially with non-default params) since app starts or after changing params, as the device may need to change its data collection.

Parameters
params	CpuHeadroomParams: params to customize the CPU headroom calculation, or null to use default.

Returns
float	a single value headroom or a Float.NaN if it's temporarily unavailable due to server error or not enough user CPU workload. Each valid value ranges from [0, 100], where 0 indicates no more cpu resources can be granted Value is between 0f and 100f inclusive

Throws
UnsupportedOperationException	if the API is unsupported.
IllegalArgumentException	if the params are invalid.
SecurityException	if the TIDs of the params don't belong to the same process.
IllegalStateException	if the TIDs of the params don't have the same affinity setting.

getCpuHeadroomCalculationWindowRange

Added in Android Baklava

public Pair<Integer, Integer> getCpuHeadroomCalculationWindowRange ()

Gets the range of the calculation window size for CPU headroom.

In API version 36, the range will be a superset of [50, 10000].

See ERROR(CpuHeadroomParams.setCalculationWindowMillis(int)/android.os.CpuHeadroomParams#setCalculationWindowMillis(int) CpuHeadroomParams.setCalculationWindowMillis(int)).

Returns
Pair<Integer, Integer>	the range of the calculation window size supported in milliseconds. This value cannot be null.

Throws
UnsupportedOperationException	if the CPU headroom API is unsupported.

getCpuHeadroomMinIntervalMillis

Added in Android Baklava

public long getCpuHeadroomMinIntervalMillis ()

Gets minimum polling interval for calling getCpuHeadroom(android.os.CpuHeadroomParams) in milliseconds.

The getCpuHeadroom(android.os.CpuHeadroomParams) API may return cached result if called more frequent than the interval.

Returns
long

Throws
UnsupportedOperationException	if the API is unsupported.

getGpuHeadroom

Added in Android Baklava

public float getGpuHeadroom (GpuHeadroomParams params)

Provides an estimate of available GPU capacity headroom of the device.

The value can be used by the calling application to determine if the workload was GPU bound and then take action accordingly to ensure that the workload can be completed smoothly. It can also be used with the thermal status and headroom to determine if reducing the GPU bound workload can help reduce the device temperature to avoid thermal throttling.

If the params are valid, each call will perform at least one synchronous binder transaction that can take more than 1ms. So it's not recommended to call or wait for this on critical threads. Some devices may implement this as an on-demand API with lazy initialization, so the caller should expect higher latency when making the first call (especially with non-default params) since app starts or after changing params, as the device may need to change its data collection.

Parameters
params	GpuHeadroomParams: params to customize the GPU headroom calculation, or null to use default.

Returns
float	a single value headroom or a Float.NaN if it's temporarily unavailable. Each valid value ranges from [0, 100], where 0 indicates no more cpu resources can be granted. Value is between 0f and 100f inclusive

Throws
UnsupportedOperationException	if the API is unsupported.
IllegalArgumentException	if the params are invalid.

getGpuHeadroomCalculationWindowRange

Added in Android Baklava

public Pair<Integer, Integer> getGpuHeadroomCalculationWindowRange ()

Gets the range of the calculation window size for GPU headroom.

In API version 36, the range will be a superset of [50, 10000].

See ERROR(GpuHeadroomParams.setCalculationWindowMillis(int)/android.os.GpuHeadroomParams#setCalculationWindowMillis(int) GpuHeadroomParams.setCalculationWindowMillis(int)).

Returns
Pair<Integer, Integer>	the range of the calculation window size supported in milliseconds. This value cannot be null.

Throws
UnsupportedOperationException	if the GPU headroom API is unsupported.

getGpuHeadroomMinIntervalMillis

Added in Android Baklava

public long getGpuHeadroomMinIntervalMillis ()

Gets minimum polling interval for calling getGpuHeadroom(android.os.GpuHeadroomParams) in milliseconds.

The getGpuHeadroom(android.os.GpuHeadroomParams) API may return cached result if called more frequent than the interval.

Returns
long

Throws
UnsupportedOperationException	if the API is unsupported.

getMaxCpuHeadroomTidsSize

Added in Android Baklava

public int getMaxCpuHeadroomTidsSize ()

Gets the maximum number of TIDs this device supports for getting CPU headroom.

See ERROR(CpuHeadroomParams.setTids(int...)/android.os.CpuHeadroomParams#setTids(int...) CpuHeadroomParams.setTids(int...)).

Returns
int	the maximum size of TIDs supported Value is 1 or greater

Throws
UnsupportedOperationException	if the CPU headroom API is unsupported.

getPowerMonitorReadings

Added in API level 35

public void getPowerMonitorReadings (List<PowerMonitor> powerMonitors, 
                Executor executor, 
                OutcomeReceiver<PowerMonitorReadings, RuntimeException> onResult)

Asynchronously retrieves the accumulated power consumption reported by the specified power monitors.

Parameters
powerMonitors	List: power monitors to be retrieved. This value cannot be null.
executor	Executor: optional Executor to deliver the callbacks. If not supplied, the callback may be invoked on an arbitrary thread. This value may be null.
onResult	OutcomeReceiver: callback for the result This value cannot be null.

getSupportedPowerMonitors

Added in API level 35

public void getSupportedPowerMonitors (Executor executor, 
                Consumer<List<PowerMonitor>> onResult)

Asynchronously retrieves a list of supported PowerMonitor's, which include raw ODPM (on-device power rail monitor) rails and modeled energy consumers. If ODPM is unsupported on this device this method delivers an empty list.

Parameters
executor	Executor: optional Handler to deliver the callback. If not supplied, the callback may be invoked on an arbitrary thread. This value may be null.
onResult	Consumer: callback for the result This value cannot be null.

takeMyUidSnapshot

Added in API level 24

public HealthStats takeMyUidSnapshot ()

Return a HealthStats object containing a snapshot of system health metrics for the application calling this API. This method is the same as calling takeUidSnapshot(Process.myUid()).

Returns
HealthStats	A HealthStats object containing the metrics for this application. The keys for this HealthStats object will be from the UidHealthStats class.

takeUidSnapshot

Added in API level 24

public HealthStats takeUidSnapshot (int uid)

Return a HealthStats object containing a snapshot of system health metrics for the given uid (user-id, which in usually corresponds to application).

Parameters
uid	int: User ID for a given application.

Returns
HealthStats	A HealthStats object containing the metrics for the requested application. The keys for this HealthStats object will be from the UidHealthStats class.

See also:

• Process.myUid()

takeUidSnapshots

Added in API level 24

public HealthStats[] takeUidSnapshots (int[] uids)

Return a HealthStats object containing a snapshot of system health metrics for the given uids (user-id, which in usually corresponds to application).

Parameters
uids	int: An array of User IDs to retrieve.

Returns
HealthStats[]	An array of HealthStats objects containing the metrics for each of the requested uids. The keys for this HealthStats object will be from the UidHealthStats class.