Added in [API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) Summary: [Methods](https://developer.android.com/reference/android/os/health/SystemHealthManager#pubmethods) \| [Inherited Methods](https://developer.android.com/reference/android/os/health/SystemHealthManager#inhmethods)
# SystemHealthManager
*** ** * ** ***
` public class SystemHealthManager `
` extends https://developer.android.com/reference/java/lang/Object ` ` `
|---|---|
| [java.lang.Object](https://developer.android.com/reference/java/lang/Object) ||
| ↳ | android.os.health.SystemHealthManager |
*** ** * ** ***
Provides access to data about how various system resources are used by applications.
## Summary
| ### Public methods ||
|---|---|
| ` float` | ` https://developer.android.com/reference/android/os/health/SystemHealthManager#getCpuHeadroom(android.os.CpuHeadroomParams)(https://developer.android.com/reference/android/os/CpuHeadroomParams params) ` Provides an estimate of available CPU capacity headroom of the device. |
| ` https://developer.android.com/reference/android/util/Pair` | ` https://developer.android.com/reference/android/os/health/SystemHealthManager#getCpuHeadroomCalculationWindowRange()() ` Gets the range of the calculation window size for CPU headroom. |
| ` long` | ` https://developer.android.com/reference/android/os/health/SystemHealthManager#getCpuHeadroomMinIntervalMillis()() ` Gets minimum polling interval for calling `https://developer.android.com/reference/android/os/health/SystemHealthManager#getCpuHeadroom(android.os.CpuHeadroomParams)` in milliseconds. |
| ` float` | ` https://developer.android.com/reference/android/os/health/SystemHealthManager#getGpuHeadroom(android.os.GpuHeadroomParams)(https://developer.android.com/reference/android/os/GpuHeadroomParams params) ` Provides an estimate of available GPU capacity headroom of the device. |
| ` https://developer.android.com/reference/android/util/Pair` | ` https://developer.android.com/reference/android/os/health/SystemHealthManager#getGpuHeadroomCalculationWindowRange()() ` Gets the range of the calculation window size for GPU headroom. |
| ` long` | ` https://developer.android.com/reference/android/os/health/SystemHealthManager#getGpuHeadroomMinIntervalMillis()() ` Gets minimum polling interval for calling `https://developer.android.com/reference/android/os/health/SystemHealthManager#getGpuHeadroom(android.os.GpuHeadroomParams)` in milliseconds. |
| ` int` | ` https://developer.android.com/reference/android/os/health/SystemHealthManager#getMaxCpuHeadroomTidsSize()() ` Gets the maximum number of TIDs this device supports for getting CPU headroom. |
| ` void` | ` https://developer.android.com/reference/android/os/health/SystemHealthManager#getPowerMonitorReadings(java.util.List,%20java.util.concurrent.Executor,%20android.os.OutcomeReceiver)(https://developer.android.com/reference/java/util/List powerMonitors, https://developer.android.com/reference/java/util/concurrent/Executor executor, https://developer.android.com/reference/android/os/OutcomeReceiver onResult) ` Asynchronously retrieves the accumulated power consumption reported by the specified power monitors. |
| ` void` | ` https://developer.android.com/reference/android/os/health/SystemHealthManager#getSupportedPowerMonitors(java.util.concurrent.Executor,%20java.util.function.Consumer>)(https://developer.android.com/reference/java/util/concurrent/Executor executor, https://developer.android.com/reference/java/util/function/Consumer> onResult) ` Asynchronously retrieves a list of supported `https://developer.android.com/reference/android/os/PowerMonitor`'s, which include raw ODPM (on-device power rail monitor) rails and modeled energy consumers. |
| ` https://developer.android.com/reference/android/os/health/HealthStats` | ` https://developer.android.com/reference/android/os/health/SystemHealthManager#takeMyUidSnapshot()() ` Return a `https://developer.android.com/reference/android/os/health/HealthStats` object containing a snapshot of system health metrics for the application calling this API. |
| ` https://developer.android.com/reference/android/os/health/HealthStats` | ` https://developer.android.com/reference/android/os/health/SystemHealthManager#takeUidSnapshot(int)(int uid) ` Return a `https://developer.android.com/reference/android/os/health/HealthStats` object containing a snapshot of system health metrics for the given uid (user-id, which in usually corresponds to application). |
| ` https://developer.android.com/reference/android/os/health/HealthStats` | ` https://developer.android.com/reference/android/os/health/SystemHealthManager#takeUidSnapshots(int[])(int[] uids) ` Return a `https://developer.android.com/reference/android/os/health/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 ` https://developer.android.com/reference/java/lang/Object ` ` https://developer.android.com/reference/java/lang/Object` ` https://developer.android.com/reference/java/lang/Object#clone()() `
Creates and returns a copy of this object.
` boolean` ` https://developer.android.com/reference/java/lang/Object#equals(java.lang.Object)(https://developer.android.com/reference/java/lang/Object obj) `
Indicates whether some other object is "equal to" this one.
` void` ` https://developer.android.com/reference/java/lang/Object#finalize()() `
Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
` final https://developer.android.com/reference/java/lang/Class` ` https://developer.android.com/reference/java/lang/Object#getClass()() `
Returns the runtime class of this `Object`.
` int` ` https://developer.android.com/reference/java/lang/Object#hashCode()() `
Returns a hash code value for the object.
` final void` ` https://developer.android.com/reference/java/lang/Object#notify()() `
Wakes up a single thread that is waiting on this object's monitor.
` final void` ` https://developer.android.com/reference/java/lang/Object#notifyAll()() `
Wakes up all threads that are waiting on this object's monitor.
` https://developer.android.com/reference/java/lang/String` ` https://developer.android.com/reference/java/lang/Object#toString()() `
Returns a string representation of the object.
` final void` ` https://developer.android.com/reference/java/lang/Object#wait(long,%20int)(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` ` https://developer.android.com/reference/java/lang/Object#wait(long)(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` ` https://developer.android.com/reference/java/lang/Object#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](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
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 ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException` | if the params are invalid. |
| `https://developer.android.com/reference/java/lang/IllegalStateException` | if the TIDs of the params don't have the same affinity setting. |
| `https://developer.android.com/reference/java/lang/SecurityException` | if the TIDs of the params don't belong to the same process. |
| `https://developer.android.com/reference/java/lang/UnsupportedOperationException` | if the API is unsupported. |
### getCpuHeadroomCalculationWindowRange
Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public Pair getCpuHeadroomCalculationWindowRange ()
```
Gets the range of the calculation window size for CPU headroom.
See `https://developer.android.com/reference/android/os/CpuHeadroomParams.Builder#setCalculationWindowMillis(int)`.
| Returns ||
|---|---|
| `https://developer.android.com/reference/android/util/Pair` | the range of the calculation window size supported in milliseconds. This value cannot be `null`.
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/UnsupportedOperationException` | if the CPU headroom API is unsupported. |
### getCpuHeadroomMinIntervalMillis
Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public long getCpuHeadroomMinIntervalMillis ()
```
Gets minimum polling interval for calling `https://developer.android.com/reference/android/os/health/SystemHealthManager#getCpuHeadroom(android.os.CpuHeadroomParams)` in milliseconds.
The `https://developer.android.com/reference/android/os/health/SystemHealthManager#getCpuHeadroom(android.os.CpuHeadroomParams)` API may return cached result if called more frequent than the interval.
| Returns ||
|---|---|
| `long` |
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/UnsupportedOperationException` | if the API is unsupported. |
### getGpuHeadroom
Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
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 0.0f and 100.0f inclusive
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException` | if the params are invalid. |
| `https://developer.android.com/reference/java/lang/UnsupportedOperationException` | if the API is unsupported. |
### getGpuHeadroomCalculationWindowRange
Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public Pair getGpuHeadroomCalculationWindowRange ()
```
Gets the range of the calculation window size for GPU headroom.
See `https://developer.android.com/reference/android/os/GpuHeadroomParams.Builder#setCalculationWindowMillis(int)`.
| Returns ||
|---|---|
| `https://developer.android.com/reference/android/util/Pair` | the range of the calculation window size supported in milliseconds. This value cannot be `null`.
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/UnsupportedOperationException` | if the GPU headroom API is unsupported. |
### getGpuHeadroomMinIntervalMillis
Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public long getGpuHeadroomMinIntervalMillis ()
```
Gets minimum polling interval for calling `https://developer.android.com/reference/android/os/health/SystemHealthManager#getGpuHeadroom(android.os.GpuHeadroomParams)` in milliseconds.
The `https://developer.android.com/reference/android/os/health/SystemHealthManager#getGpuHeadroom(android.os.GpuHeadroomParams)` API may return cached result if called more frequent than the interval.
| Returns ||
|---|---|
| `long` |
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/UnsupportedOperationException` | if the API is unsupported. |
### getMaxCpuHeadroomTidsSize
Added in [API level 36](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public int getMaxCpuHeadroomTidsSize ()
```
Gets the maximum number of TIDs this device supports for getting CPU headroom.
See `https://developer.android.com/reference/android/os/CpuHeadroomParams.Builder#setTids(int[])`.
| Returns ||
|---|---|
| `int` | the maximum size of TIDs supported. Value is 1 or greater
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/UnsupportedOperationException` | if the CPU headroom API is unsupported. |
### getPowerMonitorReadings
Added in [API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public void getPowerMonitorReadings (List powerMonitors,
Executor executor,
OutcomeReceiver 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](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public void getSupportedPowerMonitors (Executor executor,
Consumer> onResult)
```
Asynchronously retrieves a list of supported `https://developer.android.com/reference/android/os/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](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public HealthStats takeMyUidSnapshot ()
```
Return a `https://developer.android.com/reference/android/os/health/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 ||
|---|---|
| `https://developer.android.com/reference/android/os/health/HealthStats` | A `https://developer.android.com/reference/android/os/health/HealthStats` object containing the metrics for this application. The keys for this HealthStats object will be from the `https://developer.android.com/reference/android/os/health/UidHealthStats` class.
|
### takeUidSnapshot
Added in [API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public HealthStats takeUidSnapshot (int uid)
```
Return a `https://developer.android.com/reference/android/os/health/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 ||
|---|---|
| `https://developer.android.com/reference/android/os/health/HealthStats` | A `https://developer.android.com/reference/android/os/health/HealthStats` object containing the metrics for the requested application. The keys for this HealthStats object will be from the `https://developer.android.com/reference/android/os/health/UidHealthStats` class.
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/SecurityException` | if the caller attempts to retrieve stats for a uid other than its own without holding the appropriate permission. |
**See also:**
- `https://developer.android.com/reference/android/os/Process#myUid()`
### takeUidSnapshots
Added in [API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public HealthStats[] takeUidSnapshots (int[] uids)
```
Return a `https://developer.android.com/reference/android/os/health/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 ||
|---|---|
| `https://developer.android.com/reference/android/os/health/HealthStats` | An array of `https://developer.android.com/reference/android/os/health/HealthStats` objects containing the metrics for each of the requested uids. The keys for this HealthStats object will be from the `https://developer.android.com/reference/android/os/health/UidHealthStats` class.
|