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(
    boolean enableAppTagTracing,
    boolean enableUserspaceTracing,
    Function1<@NonNull PerfettoTraceUnit> traceCallback
)

Public methods

@NonNull Statement
apply(@NonNull Statement base, @NonNull Description description)
final boolean

Pass false to disable android.os.Trace API tracing in this process

final boolean

Pass true to enable userspace tracing (androidx.tracing.tracing-perfetto APIs)

final Function1<@NonNull PerfettoTraceUnit>

Callback for each captured trace.

Public constructors

PerfettoTraceRule

Added in 1.2.0
public PerfettoTraceRule(
    boolean enableAppTagTracing,
    boolean enableUserspaceTracing,
    Function1<@NonNull PerfettoTraceUnit> traceCallback
)

Public methods

apply

Added in 1.2.0
public @NonNull Statement apply(@NonNull Statement base, @NonNull Description description)

getEnableAppTagTracing

Added in 1.2.0
public final boolean getEnableAppTagTracing()

Pass false to disable android.os.Trace API tracing in this process

Defaults to true.

getEnableUserspaceTracing

Added in 1.2.0
public final boolean getEnableUserspaceTracing()

Pass true to enable userspace tracing (androidx.tracing.tracing-perfetto APIs)

Defaults to false.

getTraceCallback

Added in 1.2.0
public final Function1<@NonNull PerfettoTraceUnitgetTraceCallback()

Callback for each captured trace.