# MetricCapture

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

*** ** * ** ***


```
@ExperimentalBenchmarkConfigApi
abstract class MetricCapture
```

<br />

Known direct subclasses [TimeCapture](https://developer.android.com/reference/kotlin/androidx/benchmark/TimeCapture)

|---|---|
| `https://developer.android.com/reference/kotlin/androidx/benchmark/TimeCapture` | Time metric, which reports time in nanos, based on the time passed to `https://developer.android.com/reference/kotlin/androidx/benchmark/TimeCapture#captureStop(kotlin.Long,kotlin.LongArray,kotlin.Int)`. |

*** ** * ** ***

Microbenchmark metric.

Note that the API is designed around low overhead, even in the case of multiple submetrics (such as cpu perf event counters) that must be started/stopped together for efficiency.

This class may be initialized on a different thread from where measurement occurs, but all `capture` methods must be invoked from the same thread.

```kotlin
import androidx.benchmark.MetricCapture

/**
 * Sample shows how to collect multiple continuously running counters as metrics which measure
 * difference.
 *
 * This is similar to how [androidx.benchmark.TimeCapture] produces `timeNs`.
 */
class MyMetricCapture : MetricCapture(listOf("foo", "bar")) {
    private var currentStartedFoo = 0L
    private var currentPausedStartedFoo = 0L
    private var currentTotalPausedFoo = 0L

    private var currentStartedBar = 0L
    private var currentPausedStartedBar = 0L
    private var currentTotalPausedBar = 0L

    override fun captureStart(timeNs: Long) {
        // reset paused state, capture current
        currentTotalPausedBar = 0
        currentTotalPausedFoo = 0

        currentStartedFoo = getCurrentFoo()
        currentStartedBar = getCurrentBar()
    }

    override fun captureStop(timeNs: Long, output: LongArray, offset: Int) {
        output[offset + 0] = getCurrentFoo() - currentStartedFoo - currentTotalPausedFoo
        output[offset + 1] = getCurrentBar() - currentStartedBar - currentTotalPausedBar
    }

    override fun capturePaused() {
        currentPausedStartedFoo = getCurrentFoo()
        currentPausedStartedBar = getCurrentBar()
    }

    override fun captureResumed() {
        currentTotalPausedFoo += getCurrentFoo() - currentPausedStartedFoo
        currentTotalPausedBar += getCurrentBar() - currentPausedStartedBar
    }
}
```

## Summary

| ### Public constructors |
|---|
| `https://developer.android.com/reference/kotlin/androidx/benchmark/MetricCapture#MetricCapture(kotlin.collections.List)(names: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html>)` |

| ### Public functions |
|---|---|
| `abstract https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/benchmark/MetricCapture#capturePaused()()` Pause data collection. |
| `abstract https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/benchmark/MetricCapture#captureResumed()()` Resume data collection |
| `abstract https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/benchmark/MetricCapture#captureStart(kotlin.Long)(timeNs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html)` Starts collecting data for a run. |
| `abstract https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/benchmark/MetricCapture#captureStop(kotlin.Long,kotlin.LongArray,kotlin.Int)(timeNs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html, output: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long-array/index.html, offset: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Mark the end of a run, and store offset metrics in the output array, per sub metric. |
| `open operator https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/benchmark/MetricCapture#equals(kotlin.Any)(other: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?)` |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/benchmark/MetricCapture#hashCode()()` |

| ### Public properties |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html>` | `https://developer.android.com/reference/kotlin/androidx/benchmark/MetricCapture#names()` List of names of metrics produced by this MetricCapture. |

## Public constructors

### MetricCapture

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

```
MetricCapture(names: List<String>)
```

## Public functions

### capturePaused

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

```
abstract fun capturePaused(): Unit
```

Pause data collection.

### captureResumed

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

```
abstract fun captureResumed(): Unit
```

Resume data collection

### captureStart

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

```
abstract fun captureStart(timeNs: Long): Unit
```

Starts collecting data for a run.

Called at the start of each run.

| Parameters |
|---|---|
| `timeNs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html` | Current time, just before starting metrics. Can be used directly to drive a timing metric produced. |

### captureStop

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

```
abstract fun captureStop(timeNs: Long, output: LongArray, offset: Int): Unit
```

Mark the end of a run, and store offset metrics in the output array, per sub metric.

To output values, store them in the output array offset by both the parameter offset, and their submetric index.

| Parameters |
|---|---|
| `timeNs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html` | Time of metric capture start, in monotonic time (`https://developer.android.com/reference/java/lang/System.html#nanoTime()`) |
| `output: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long-array/index.html` | LongArray sized to hold all simultaneous sub metric outputs, use `offset` as the initial position in `output` to start writing submetrics. |
| `offset: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | Offset into the output array to start writing sub metrics. |

### equals

```
open operator fun equals(other: Any?): Boolean
```

### hashCode

```
open fun hashCode(): Int
```

## Public properties

### names

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

```
val names: List<String>
```

List of names of metrics produced by this MetricCapture.

The length of this list defines how many metrics will be produced by `https://developer.android.com/reference/kotlin/androidx/benchmark/MetricCapture#captureStart(kotlin.Long)` and `https://developer.android.com/reference/kotlin/androidx/benchmark/MetricCapture#captureStop(kotlin.Long,kotlin.LongArray,kotlin.Int)`.