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 API level 36

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 0.0f and 100.0f 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 API level 36

public Pair<Integer, Integer> getCpuHeadroomCalculationWindowRange ()

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

See CpuHeadroomParams.Builder.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 API level 36

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 API level 36

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.

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 0.0f and 100.0f inclusive

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

getGpuHeadroomCalculationWindowRange

Added in API level 36

public Pair<Integer, Integer> getGpuHeadroomCalculationWindowRange ()

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

See GpuHeadroomParams.Builder.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 API level 36

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 API level 36

public int getMaxCpuHeadroomTidsSize ()

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

See CpuHeadroomParams.Builder.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.