Added in API level 24

SystemHealthManager

open class SystemHealthManager
kotlin.Any
   ↳ android.os.health.SystemHealthManager

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

Summary

Public methods
open Float

Provides an estimate of available CPU capacity headroom of the device.
open Pair<Int!, Int!>

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

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

Provides an estimate of available GPU capacity headroom of the device.
open Pair<Int!, Int!>

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

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

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

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

Asynchronously retrieves a list of supported PowerMonitor's, which include raw ODPM (on-device power rail monitor) rails and modeled energy consumers.
open HealthStats!

Return a HealthStats object containing a snapshot of system health metrics for the application calling this API.
open HealthStats!

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

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

Public methods

getCpuHeadroom

Added in API level Baklava
open fun getCpuHeadroom(params: CpuHeadroomParams?): Float

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.
Return
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
Exceptions
java.lang.UnsupportedOperationException if the API is unsupported.
java.lang.IllegalArgumentException if the params are invalid.
java.lang.SecurityException if the TIDs of the params don't belong to the same process.
java.lang.IllegalStateException if the TIDs of the params don't have the same affinity setting.

getCpuHeadroomCalculationWindowRange

Added in API level Baklava
open fun getCpuHeadroomCalculationWindowRange(): Pair<Int!, Int!>

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 android.os.CpuHeadroomParams#setCalculationWindowMillis(int).

Return
Pair<Int!, Int!> the range of the calculation window size supported in milliseconds. This value cannot be null.
Exceptions
java.lang.UnsupportedOperationException if the CPU headroom API is unsupported.

getCpuHeadroomMinIntervalMillis

Added in API level Baklava
open fun getCpuHeadroomMinIntervalMillis(): Long

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.

Exceptions
java.lang.UnsupportedOperationException if the API is unsupported.

getGpuHeadroom

Added in API level Baklava
open fun getGpuHeadroom(params: GpuHeadroomParams?): Float

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.
Return
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
Exceptions
java.lang.UnsupportedOperationException if the API is unsupported.
java.lang.IllegalArgumentException if the params are invalid.

getGpuHeadroomCalculationWindowRange

Added in API level Baklava
open fun getGpuHeadroomCalculationWindowRange(): Pair<Int!, Int!>

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 android.os.GpuHeadroomParams#setCalculationWindowMillis(int).

Return
Pair<Int!, Int!> the range of the calculation window size supported in milliseconds. This value cannot be null.
Exceptions
java.lang.UnsupportedOperationException if the GPU headroom API is unsupported.

getGpuHeadroomMinIntervalMillis

Added in API level Baklava
open fun getGpuHeadroomMinIntervalMillis(): Long

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.

Exceptions
java.lang.UnsupportedOperationException if the API is unsupported.

getMaxCpuHeadroomTidsSize

Added in API level Baklava
open fun getMaxCpuHeadroomTidsSize(): Int

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

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

Return
Int the maximum size of TIDs supported Value is 1 or greater
Exceptions
java.lang.UnsupportedOperationException if the CPU headroom API is unsupported.

getPowerMonitorReadings

Added in API level 35
open fun getPowerMonitorReadings(
    powerMonitors: MutableList<PowerMonitor!>, 
    executor: Executor?, 
    onResult: OutcomeReceiver<PowerMonitorReadings!, RuntimeException!>
): Unit

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

Parameters
powerMonitors MutableList<PowerMonitor!>: 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<PowerMonitorReadings!, RuntimeException!>: callback for the result This value cannot be null.

getSupportedPowerMonitors

Added in API level 35
open fun getSupportedPowerMonitors(
    executor: Executor?, 
    onResult: Consumer<MutableList<PowerMonitor!>!>
): Unit

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<MutableList<PowerMonitor!>!>: callback for the result This value cannot be null.

takeMyUidSnapshot

Added in API level 24
open fun takeMyUidSnapshot(): HealthStats!

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

Return
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
open fun takeUidSnapshot(uid: Int): HealthStats!

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.
Return
HealthStats! A HealthStats object containing the metrics for the requested application. The keys for this HealthStats object will be from the UidHealthStats class.

takeUidSnapshots

Added in API level 24
open fun takeUidSnapshots(uids: IntArray!): Array<HealthStats!>!

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 IntArray!: An array of User IDs to retrieve.
Return
Array<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.