# 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
public final class PerfettoTraceRule implements TestRule
```

<br />

*** ** * ** ***

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

```
@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:

```
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.

```
> 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/androidx/benchmark/junit4/PerfettoTraceRule#PerfettoTraceRule(androidx.benchmark.perfetto.PerfettoConfig,kotlin.Boolean,kotlin.Function1,kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/perfetto/PerfettoConfig config, boolean enableUserspaceTracing, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html> labelProvider, Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/traceprocessor/PerfettoTrace, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> traceCallback )` |
| `https://developer.android.com/reference/androidx/benchmark/junit4/PerfettoTraceRule#PerfettoTraceRule(kotlin.Boolean,kotlin.Boolean,androidx.benchmark.InProcessTracingMode,kotlin.Function1,kotlin.Function1)( boolean enableAppTagTracing, boolean enableUserspaceTracing, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/InProcessTracingMode inProcessTracingMode, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html> labelProvider, Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/traceprocessor/PerfettoTrace, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> traceCallback )` |

| ### Public methods |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://junit.org/junit4/javadoc/latest/org/junit/runners/model/Statement.html` | `https://developer.android.com/reference/androidx/benchmark/junit4/PerfettoTraceRule#apply(org.junit.runners.model.Statement,org.junit.runner.Description)(@https://developer.android.com/reference/androidx/annotation/NonNull https://junit.org/junit4/javadoc/latest/org/junit/runners/model/Statement.html base, @https://developer.android.com/reference/androidx/annotation/NonNull https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html description)` |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/perfetto/PerfettoConfig` | `https://developer.android.com/reference/androidx/benchmark/junit4/PerfettoTraceRule#getConfig()()` Config used to record Perfetto trace. |
| `final boolean` | `https://developer.android.com/reference/androidx/benchmark/junit4/PerfettoTraceRule#getEnableUserspaceTracing()()` Pass true to enable userspace tracing. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.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/junit4/PerfettoTraceRule#getLabelProvider()()` Configure the label, used both as the filename prefix for the trace, and label shown in Android Studio. |
| `final Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/traceprocessor/PerfettoTrace, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html>` | `https://developer.android.com/reference/androidx/benchmark/junit4/PerfettoTraceRule#getTraceCallback()()` Callback for each captured trace. |

## Public constructors

### PerfettoTraceRule

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

```
public PerfettoTraceRule(
    @NonNull PerfettoConfig config,
    boolean enableUserspaceTracing,
    @NonNull Function1<@NonNull Description, @NonNull String> labelProvider,
    Function1<@NonNull PerfettoTrace, Unit> traceCallback
)
```

### PerfettoTraceRule

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

```
public PerfettoTraceRule(
    boolean enableAppTagTracing,
    boolean enableUserspaceTracing,
    @NonNull InProcessTracingMode inProcessTracingMode,
    @NonNull Function1<@NonNull Description, @NonNull String> labelProvider,
    Function1<@NonNull PerfettoTrace, Unit> traceCallback
)
```

## Public methods

### apply

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

```
public @NonNull Statement apply(@NonNull Statement base, @NonNull Description description)
```

### getConfig

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

```
public final @NonNull PerfettoConfig getConfig()
```

Config used to record Perfetto trace.

### getEnableUserspaceTracing

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

```
public final boolean getEnableUserspaceTracing()
```

Pass true to enable userspace tracing.

Defaults to false.

### getLabelProvider

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

```
public final @NonNull Function1<@NonNull Description, @NonNull String> getLabelProvider()
```

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 \`_

### getTraceCallback

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

```
public final Function1<@NonNull PerfettoTrace, Unit> getTraceCallback()
```

Callback for each captured trace.