PerfettoTraceRule


@ExperimentalPerfettoCaptureApi
class PerfettoTraceRule : 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(
    enableAppTagTracing: Boolean,
    enableUserspaceTracing: Boolean,
    traceCallback: ((PerfettoTrace) -> Unit)?
)

Public functions

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

Public properties

Boolean

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

Boolean

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

((PerfettoTrace) -> Unit)?

Callback for each captured trace.

Public constructors

PerfettoTraceRule

Added in 1.2.0
PerfettoTraceRule(
    enableAppTagTracing: Boolean = true,
    enableUserspaceTracing: Boolean = false,
    traceCallback: ((PerfettoTrace) -> Unit)? = null
)

Public functions

apply

Added in 1.2.0
open fun apply(base: Statement, description: Description): Statement

Public properties

enableAppTagTracing

Added in 1.2.0
val enableAppTagTracingBoolean

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

Defaults to true.

enableUserspaceTracing

Added in 1.2.0
val enableUserspaceTracingBoolean

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

Defaults to false.

traceCallback

Added in 1.2.0
val traceCallback: ((PerfettoTrace) -> Unit)?

Callback for each captured trace.