TraceMetric

@ExperimentalMetricApi
abstract class TraceMetric : Metric

kotlin.Any
   ↳ androidx.benchmark.macro.Metric
     ↳ androidx.benchmark.macro.TraceMetric
Known direct subclasses
MemoryCountersMetric

Captures the number of page faults over time for a target package name.
MemoryUsageMetric

Metric for tracking the memory usage of the target application.

Metric which captures results from a Perfetto trace with custom TraceProcessor queries.

This is a more customizable version of TraceSectionMetric which can perform arbitrary queries against the captured PerfettoTrace.

Sample metric which finds the duration of the first "activityResume" trace section for the traced package:

class ActivityResumeMetric : TraceMetric() {
    override fun getMeasurements(
        captureInfo: CaptureInfo,
        traceSession: TraceProcessor.Session
    ): List<Measurement> {
        val rowSequence = traceSession.query(
            """
            SELECT
                slice.name as name,
                slice.ts as ts,
                slice.dur as dur
            FROM slice
                INNER JOIN thread_track on slice.track_id = thread_track.id
                INNER JOIN thread USING(utid)
                INNER JOIN process USING(upid)
            WHERE
                process.name LIKE ${captureInfo.targetPackageName}
                    AND slice.name LIKE "activityResume"
            """.trimIndent()
        )
        // this metric queries a single slice type to produce submetrics, but could be extended
        // to capture timing of every component of activity lifecycle
        val activityResultNs = rowSequence.firstOrNull()?.double("dur")
        return if (activityResultMs != null) {
            listOf(Measurement("activityResumeMs", activityResultNs / 1_000_000.0))
        } else {
            emptyList()
        }
    }
}
See also
TraceProcessor
TraceProcessor.Session
query

Summary

Public constructors

Public functions
abstract List<Metric.Measurement>
getMeasurements(
    captureInfo: Metric.CaptureInfo,
    traceSession: TraceProcessor.Session
)

Get the metric result for a given iteration given information about the target process and a TraceProcessor session

Public constructors

TraceMetric

Added in 1.2.0
TraceMetric()

Public functions

getMeasurements

Added in 1.4.0
abstract fun getMeasurements(
    captureInfo: Metric.CaptureInfo,
    traceSession: TraceProcessor.Session
): List<Metric.Measurement>

Get the metric result for a given iteration given information about the target process and a TraceProcessor session

import androidx.benchmark.macro.ExperimentalMetricApi
import androidx.benchmark.macro.TraceMetric
import androidx.benchmark.traceprocessor.TraceProcessor

/**
 * Calculates latency of sections where begin and end trace points are in different processes.
 *
 * @param beginPointName Name of begin tracepoint.
 * @param endPointName Name of end tracepoint.
 * @param eventName Name of the final metric that is spit out after the test run. The metric
 *   name will be {$eventName}LatencyMillis.
 */
@OptIn(ExperimentalMetricApi::class)
class CrossProcessLatencyMetricSample(
    private val beginPointName: String,
    private val endPointName: String,
    private val eventName: String,
) : TraceMetric() {
    @OptIn(ExperimentalMetricApi::class)
    override fun getMeasurements(
        captureInfo: CaptureInfo,
        traceSession: TraceProcessor.Session,
    ): List<Measurement> {
        val query =
            """
         INCLUDE perfetto module slices.with_context;
         SELECT
             event,
             ts2-ts1 AS latency_in_nanos
         FROM
         (
           (SELECT
               ts AS ts1,
               "event" AS event,
               LOWER(TRIM(process_name)) as process_name_1
               FROM thread_slice WHERE name = '${beginPointName}'
           )
           LEFT JOIN
           (SELECT
               ts AS ts2,
               "event" AS event,
               LOWER(TRIM(process_name)) as process_name_2
               FROM thread_slice WHERE name = '${endPointName}'
           )
           USING (event)
         )
           """
                .trimIndent() // maybe add checks for process name etc too in query

        val rowSequence = traceSession.query(query)
        // First row (or null) is returned.
        val latencyResultNanos = rowSequence.firstOrNull()?.long("latency_in_nanos")
        return if (latencyResultNanos != null) {
            listOf(Measurement(eventName + "LatencyMillis", latencyResultNanos / 1_000_000.0))
        } else {
            emptyList()
        }
    }
}