# PowerMetric

Artifact: [androidx.benchmark:benchmark-macro](https://developer.android.com/jetpack/androidx/releases/benchmark) [View Source](https://cs.android.com/search?q=file:androidx/benchmark/macro/Metric.kt+class:androidx.benchmark.macro.PowerMetric) Added in [1.2.0](https://developer.android.com/jetpack/androidx/releases/benchmark#1.2.0)

*** ** * ** ***


```
@RequiresApi(value = 29)
@ExperimentalMetricApi
public final class PowerMetric extends Metric
```

<br />

|---|---|---|
| [java.lang.Object](https://developer.android.com/reference/java/lang/Object.html) |||
| ↳ | [androidx.benchmark.macro.Metric](https://developer.android.com/reference/androidx/benchmark/macro/Metric) ||
|   | ↳ | [androidx.benchmark.macro.PowerMetric](https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric) |

*** ** * ** ***

Captures the change of power, energy or battery charge metrics over time for specified duration. A configurable output of power, energy, subsystems, and battery charge will be generated. Subsystem outputs will include the sum of all power or energy metrics within it. A metric total will also be generated for power and energy, as well as a metric which is the sum of all unselected metrics.

## Summary

| ### Nested types |
|---|
| `public sealed class https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric.Type` Configures the PowerMetric request. |
| `public final class https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric.Type.Battery extends https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric.Type` |
| `public final class https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric.Type.Energy extends https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric.Type` |
| `public final class https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric.Type.Power extends https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric.Type` |

| ### Public constructors |
|---|
| `https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric#PowerMetric(androidx.benchmark.macro.PowerMetric.Type)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric.Type type)` |

| ### Public methods |
|---|---|
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric.Type.Battery` | `https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric#Battery()()` |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric.Type.Energy` | `https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric#Energy(kotlin.collections.Map)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/Map.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/PowerCategory, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/PowerCategoryDisplayLevel> categories )` |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric.Type.Power` | `https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric#Power(kotlin.collections.Map)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/Map.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/PowerCategory, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/PowerCategoryDisplayLevel> categories )` |
| `static final boolean` | `https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric#deviceBatteryHasMinimumCharge()()` Returns true if `https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric.Type.Battery` measurements can be performed, based on current device charge. |
| `static final boolean` | `https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric#deviceSupportsHighPrecisionTracking()()` Returns true if the current device can be used for high precision `https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric#Power(kotlin.collections.Map)` and `https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric#Energy(kotlin.collections.Map)` metrics. |

## Public constructors

### PowerMetric

Added in [1.2.0](https://developer.android.com/jetpack/androidx/releases/benchmark#1.2.0)

```
public PowerMetric(@NonNull PowerMetric.Type type)
```

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric.Type type` | Either `https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric.Type.Energy` or `https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric.Type.Power`, which can be configured to show components of system power usage, or `https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric.Type.Battery`, which will halt charging of device to measure power drain. For `https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric.Type.Energy` or `https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric.Type.Power`, the sum of all categories will be displayed as a `Total` metric. The sum of all unrequested categories will be displayed as an `Unselected` metric. The subsystems that have not been categorized will be displayed as an `Uncategorized` metric. You can check if the local device supports this high precision tracking with `https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric#deviceSupportsHighPrecisionTracking()`. For `https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric.Type.Battery`, the charge for the start of the run and the end of the run will be displayed. An additional `Diff` metric will be displayed to indicate the charge drain over the course of the test. The metrics will be stored in the format `<type><name><unit>`. This outputs measurements like the following: Power metrics example: ``` powerCategoryDisplayUw       min       128.2,   median       128.7,   max       129.8 powerComponentCpuBigUw       min         1.9,   median         2.9,   max         3.4 powerComponentCpuLittleUw    min        65.8,   median        76.2,   max        79.7 powerComponentCpuMidUw       min        10.8,   median        13.3,   max        13.6 powerTotalUw                 min       362.4,   median       395.2,   max       400.6 powerUnselectedUw            min       155.3,   median       170.8,   max       177.8 ``` Energy metrics example: ``` energyCategoryDisplayUws     min    610,086.0,   median    623,183.0,   max    627,259.0 energyComponentCpuBigUws     min      9,233.0,   median     13,566.0,   max     16,536.0 energyComponentCpuLittleUws  min    318,591.0,   median    368,211.0,   max    379,106.0 energyComponentCpuMidUws     min     52,143.0,   median     64,462.0,   max     64,893.0 energyTotalUws               min  1,755,261.0,   median  1,880,687.0,   max  1,935,402.0 energyUnselectedUws          min    752,111.0,   median    813,036.0,   max    858,934.0 ``` Battery metrics example: ``` batteryDiffMah       min         2.0,   median         2.0,   max         4.0 batteryEndMah        min     3,266.0,   median     3,270.0,   max     3,276.0 batteryStartMah      min     3,268.0,   median     3,274.0,   max     3,278.0 ``` This measurement is not available prior to API 29. |

## Public methods

### Battery

Added in [1.2.0](https://developer.android.com/jetpack/androidx/releases/benchmark#1.2.0)

```
public static final @NonNull PowerMetric.Type.Battery Battery()
```

### Energy

```
public static final @NonNull PowerMetric.Type.Energy Energy(
    @NonNull Map<@NonNull PowerCategory, @NonNull PowerCategoryDisplayLevel> categories
)
```

### Power

```
public static final @NonNull PowerMetric.Type.Power Power(
    @NonNull Map<@NonNull PowerCategory, @NonNull PowerCategoryDisplayLevel> categories
)
```

### deviceBatteryHasMinimumCharge

Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/benchmark#1.3.0)

```
public static final boolean deviceBatteryHasMinimumCharge()
```

Returns true if `https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric.Type.Battery` measurements can be performed, based on current device charge.

This can be used to change behavior or throw a clear error before metric configuration, or to skip the test, e.g. with `assumeTrue(PowerMetric.deviceBatteryHasMinimumCharge())`

### deviceSupportsHighPrecisionTracking

Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/benchmark#1.3.0)

```
public static final boolean deviceSupportsHighPrecisionTracking()
```

Returns true if the current device can be used for high precision `https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric#Power(kotlin.collections.Map)` and `https://developer.android.com/reference/androidx/benchmark/macro/PowerMetric#Energy(kotlin.collections.Map)` metrics.

This can be used to change behavior or fall back to lower precision tracking:

```
metrics = listOf(
    if (PowerMetric.deviceSupportsHighPrecisionTracking()) {
        PowerMetric(Type.Energy()) // high precision tracking
    } else {
        PowerMetric(Type.Battery()) // fall back to less precise tracking
    }
)
```

Or to skip a test when detailed tracking isn't available:

```
@Test fun myDetailedPowerBenchmark {
    assumeTrue(PowerMetric.deviceSupportsHighPrecisionTracking())
    macrobenchmarkRule.measureRepeated (
        metrics = listOf(PowerMetric(Type.Energy(...)))
    ) {
        ...
    }
}
```