# PerfettoTraceRule

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

*** ** * ** ***


```
@ExperimentalPerfettoCaptureApi
class PerfettoTraceRule : TestRule
```

<br />

*** ** * ** ***

Add this rule to record a Perfetto trace for each test on Android Lollipop (API 21)+ devices.

```kotlin
@RunWith(AndroidJUnit4::class)
class PerfettoOverheadBenchmark {
    // traces all tests in file
    @get:Rule
    val perfettoRule = PerfettoTraceRule()

    @Test
    fun test() {}
}
```

Captured traces can be observed through any of:

- Android Studio trace linking under `Benchmark` in test output tab

- The optional `traceCallback` parameter

- Android Gradle defining and pulling the file via additionalTestOutputDir.

When invoked via Gradle, files will be copied to host path like the following:

```kotlin
out/build/outputs/connected_android_test_additional_output/debugAndroidTest/connected/<deviceName>/androidx.mypackage.TestClass_testMethod.perfetto-trace
```

You can additionally check logcat for messages tagged "PerfettoCapture:" for the path of each perfetto trace.

```kotlin
> adb pull /storage/emulated/0/Android/data/mypackage.test/files/PerfettoCaptureTest.trace
```

Reentrant Perfetto trace capture is not supported, so this API may not be combined with `BenchmarkRule`, `MacrobenchmarkRule`, or `PerfettoTrace.record`.

## Summary

| ### Public constructors |
|---|
| `https://developer.android.com/reference/kotlin/androidx/benchmark/junit4/PerfettoTraceRule#PerfettoTraceRule(androidx.benchmark.perfetto.PerfettoConfig,kotlin.Boolean,kotlin.Function1,kotlin.Function1)( config: https://developer.android.com/reference/kotlin/androidx/benchmark/perfetto/PerfettoConfig, enableUserspaceTracing: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, labelProvider: (https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, traceCallback: ((https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/PerfettoTrace) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)? )` |
| `https://developer.android.com/reference/kotlin/androidx/benchmark/junit4/PerfettoTraceRule#PerfettoTraceRule(kotlin.Boolean,kotlin.Boolean,androidx.benchmark.InProcessTracingMode,kotlin.Function1,kotlin.Function1)( enableAppTagTracing: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, enableUserspaceTracing: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, inProcessTracingMode: https://developer.android.com/reference/kotlin/androidx/benchmark/InProcessTracingMode, labelProvider: (https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, traceCallback: ((https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/PerfettoTrace) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)? )` |

| ### Public functions |
|---|---|
| `open https://junit.org/junit4/javadoc/latest/org/junit/runners/model/Statement.html` | `https://developer.android.com/reference/kotlin/androidx/benchmark/junit4/PerfettoTraceRule#apply(org.junit.runners.model.Statement,org.junit.runner.Description)(base: https://junit.org/junit4/javadoc/latest/org/junit/runners/model/Statement.html, description: https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html)` |

| ### Public properties |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/benchmark/perfetto/PerfettoConfig` | `https://developer.android.com/reference/kotlin/androidx/benchmark/junit4/PerfettoTraceRule#config()` Config used to record Perfetto trace. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/benchmark/junit4/PerfettoTraceRule#enableUserspaceTracing()` Pass true to enable userspace tracing. |
| `(https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | `https://developer.android.com/reference/kotlin/androidx/benchmark/junit4/PerfettoTraceRule#labelProvider()` Configure the label, used both as the filename prefix for the trace, and label shown in Android Studio. |
| `((https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/PerfettoTrace) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)?` | `https://developer.android.com/reference/kotlin/androidx/benchmark/junit4/PerfettoTraceRule#traceCallback()` Callback for each captured trace. |

## Public constructors

### PerfettoTraceRule

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

```
PerfettoTraceRule(
    config: PerfettoConfig,
    enableUserspaceTracing: Boolean = false,
    labelProvider: (Description) -> String = { description ->
        "${description.className}_${description.methodName}"
    },
    traceCallback: ((PerfettoTrace) -> Unit)? = null
)
```

### PerfettoTraceRule

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

```
PerfettoTraceRule(
    enableAppTagTracing: Boolean = true,
    enableUserspaceTracing: Boolean = false,
    inProcessTracingMode: InProcessTracingMode = InProcessTracingMode.Disable,
    labelProvider: (Description) -> String = { description ->
            "${description.className}_${description.methodName}"
        },
    traceCallback: ((PerfettoTrace) -> Unit)? = null
)
```

## Public functions

### apply

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

```
open fun apply(base: Statement, description: Description): Statement
```

## Public properties

### config

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

```
val config: PerfettoConfig
```

Config used to record Perfetto trace.

### enableUserspaceTracing

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

```
val enableUserspaceTracing: Boolean
```

Pass true to enable userspace tracing.

Defaults to false.

### labelProvider

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

```
val labelProvider: (Description) -> String
```

Configure the label, used both as the filename prefix for the trace, and label shown in Android Studio.

The final output file will be named: `<labelCallbackResult>_<yyyy-MM-dd-HH-mm-ss>.perfetto-trace`

Defaults to \`_

### traceCallback

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

```
val traceCallback: ((PerfettoTrace) -> Unit)?
```

Callback for each captured trace.