PerfettoTraceRule

@ExperimentalPerfettoCaptureApi
public final class PerfettoTraceRule implements TestRule

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
PerfettoTraceRule(
    @NonNull PerfettoConfig config,
    boolean enableUserspaceTracing,
    @NonNull Function1<@NonNull Description, @NonNull String> labelProvider,
    Function1<@NonNull PerfettoTrace, Unit> traceCallback
)
PerfettoTraceRule(
    boolean enableAppTagTracing,
    boolean enableUserspaceTracing,
    @NonNull InProcessTracingMode inProcessTracingMode,
    @NonNull Function1<@NonNull Description, @NonNull String> labelProvider,
    Function1<@NonNull PerfettoTrace, Unit> traceCallback
)

Public methods
@NonNull Statement
apply(@NonNull Statement base, @NonNull Description description)
final @NonNull PerfettoConfig

Config used to record Perfetto trace.
final boolean

Pass true to enable userspace tracing.
final @NonNull Function1<@NonNull Description, @NonNull String>

Configure the label, used both as the filename prefix for the trace, and label shown in Android Studio.
final Function1<@NonNull PerfettoTrace, Unit>

Callback for each captured trace.

Public constructors

PerfettoTraceRule

Added in 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
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
public @NonNull Statement apply(@NonNull Statement base, @NonNull Description description)

getConfig

Added in 1.4.0
public final @NonNull PerfettoConfig getConfig()

Config used to record Perfetto trace.

getEnableUserspaceTracing

Added in 1.2.0
public final boolean getEnableUserspaceTracing()

Pass true to enable userspace tracing.

Defaults to false.

getLabelProvider

Added in 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
public final Function1<@NonNull PerfettoTrace, Unit> getTraceCallback()

Callback for each captured trace.