# 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
public abstract class MetricCapture
```

<br />

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

|---|---|
| `https://developer.android.com/reference/androidx/benchmark/TimeCapture` | Time metric, which reports time in nanos, based on the time passed to `https://developer.android.com/reference/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/androidx/benchmark/MetricCapture#MetricCapture(kotlin.collections.List)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html> names)` |

| ### Public methods |
|---|---|
| `abstract void` | `https://developer.android.com/reference/androidx/benchmark/MetricCapture#capturePaused()()` Pause data collection. |
| `abstract void` | `https://developer.android.com/reference/androidx/benchmark/MetricCapture#captureResumed()()` Resume data collection |
| `abstract void` | `https://developer.android.com/reference/androidx/benchmark/MetricCapture#captureStart(kotlin.Long)(long timeNs)` Starts collecting data for a run. |
| `abstract void` | `https://developer.android.com/reference/androidx/benchmark/MetricCapture#captureStop(kotlin.Long,kotlin.LongArray,kotlin.Int)(long timeNs, @https://developer.android.com/reference/androidx/annotation/NonNull long[] output, int offset)` Mark the end of a run, and store offset metrics in the output array, per sub metric. |
| `boolean` | `https://developer.android.com/reference/androidx/benchmark/MetricCapture#equals(kotlin.Any)(https://developer.android.com/reference/java/lang/Object.html other)` |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html>` | `https://developer.android.com/reference/androidx/benchmark/MetricCapture#getNames()()` List of names of metrics produced by this MetricCapture. |
| `int` | `https://developer.android.com/reference/androidx/benchmark/MetricCapture#hashCode()()` |

## Public constructors

### MetricCapture

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

```
public MetricCapture(@NonNull List<@NonNull String> names)
```

## Public methods

### capturePaused

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

```
public abstract void capturePaused()
```

Pause data collection.

### captureResumed

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

```
public abstract void captureResumed()
```

Resume data collection

### captureStart

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

```
public abstract void captureStart(long timeNs)
```

Starts collecting data for a run.

Called at the start of each run.

| Parameters |
|---|---|
| `long timeNs` | 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)

```
public abstract void captureStop(long timeNs, @NonNull long[] output, int offset)
```

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 |
|---|---|
| `long timeNs` | Time of metric capture start, in monotonic time (`https://developer.android.com/reference/java/lang/System.html#nanoTime()`) |
| `@https://developer.android.com/reference/androidx/annotation/NonNull long[] output` | LongArray sized to hold all simultaneous sub metric outputs, use `offset` as the initial position in `output` to start writing submetrics. |
| `int offset` | Offset into the output array to start writing sub metrics. |

### equals

```
public boolean equals(Object other)
```

### getNames

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

```
public final @NonNull List<@NonNull String> getNames()
```

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/androidx/benchmark/MetricCapture#captureStart(kotlin.Long)` and `https://developer.android.com/reference/androidx/benchmark/MetricCapture#captureStop(kotlin.Long,kotlin.LongArray,kotlin.Int)`.

### hashCode

```
public int hashCode()
```