public final class TraceProcessor


Kotlin API for Perfetto Trace Processor, which enables SQL querying against the data stored in a Perfetto trace.

This includes synchronous and async trace sections, kernel-level scheduling timing, binder events... If it's displayed in Android Studio system trace or ui.perfetto.dev, it can be queried from this API.

import androidx.benchmark.macro.runServer
import androidx.benchmark.traceprocessor.PerfettoTrace
import androidx.benchmark.traceprocessor.TraceProcessor

// Collect the duration of all slices named "activityStart" in the trace
val activityStartDurNs =
    TraceProcessor.runServer {
        loadTrace(PerfettoTrace("/path/to/trace.perfetto-trace")) {
                query("SELECT dur FROM slice WHERE name = 'activityStart'").map {
                    it.long("dur")
                }
            }
            .toList()
    }
return activityStartDurNs

Note that traces generally hold events from multiple apps, services and processes, so it's recommended to filter potentially common trace events to the process you're interested in. See the following example which queries Choreographer#doFrame slices (labelled spans of time) only for a given package name:

import androidx.benchmark.traceprocessor.PerfettoTrace

loadTrace(PerfettoTrace("/path/to/trace.perfetto-trace")) {
    query(
            """
        |SELECT
        |    slice.name, slice.ts, slice.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
        |    slice.name LIKE "Choreographer#doFrame%" AND
        |    process.name = "$packageName"
        """
                .trimMargin()
        )
        .forEach {
            // process each observed doFrame slice
            doFrameCallback(it.string("name"), it.long("ts"), it.long("dur"))
        }
}

See also Perfetto project documentation:

See also
PerfettoTrace

Summary

Nested types

public static class TraceProcessor.Companion
public final class TraceProcessor.Handle
public final class TraceProcessor.Session

Handle to query sql data from a PerfettoTrace.

Public constructors

Public methods

final @NonNull T
<T extends Object> loadTrace(
    @NonNull PerfettoTrace trace,
    @ExtensionFunctionType @NonNull Function1<@NonNull TraceProcessor.Session, @NonNull T> block
)

Loads a PerfettoTrace into the trace processor server to query data out of the trace.

final @NonNull TraceProcessor.Session.Handle

Loads a PerfettoTrace into the TraceProcessor server, and returns a Session.Handle which can be used to access and close a Session.

Public constructors

TraceProcessor

@<Error class: unknown class>
@ExperimentalTraceProcessorApi
public TraceProcessor(
    @NonNull ServerLifecycleManager serverLifecycleManager,
    @NonNull TraceProcessor.Tracer tracer,
    @NonNull TraceProcessor.EventCallback eventCallback,
    @NonNull Duration timeout
)

Public methods

loadTrace

Added in 1.4.0-alpha10
public final @NonNull T <T extends Object> loadTrace(
    @NonNull PerfettoTrace trace,
    @ExtensionFunctionType @NonNull Function1<@NonNull TraceProcessor.Session, @NonNull T> block
)

Loads a PerfettoTrace into the trace processor server to query data out of the trace.

startSession

Added in 1.4.0-alpha10
public final @NonNull TraceProcessor.Session.Handle startSession(@NonNull PerfettoTrace trace)

Loads a PerfettoTrace into the TraceProcessor server, and returns a Session.Handle which can be used to access and close a Session.