PerfettoTraceProcessor


@ExperimentalPerfettoTraceProcessorApi
public final class PerfettoTraceProcessor


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.

// Collect the duration of all slices named "activityStart" in the trace
val
activityStartDurationNs = PerfettoTraceProcessor.runServer {
loadTrace(trace) {
query("SELECT dur FROM slice WHERE name LIKE \"activityStart\"").toList {
it.long("dur")
}
}
}

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:

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 LIKE "
$packageName"
"""
.trimMargin()
)

See also Perfetto project documentation:

See also
PerfettoTrace

Summary

Nested types

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 PerfettoTraceProcessor.Session, @NonNull T> block
)

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

static final @NonNull T
<T extends Object> runServer(
    @ExtensionFunctionType @NonNull Function1<@NonNull PerfettoTraceProcessor, @NonNull T> block
)

Starts a Perfetto trace processor shell server in http mode, loads a trace and executes the given block.

static final @NonNull T
<T extends Object> runServer(
    @NonNull Duration timeout,
    @ExtensionFunctionType @NonNull Function1<@NonNull PerfettoTraceProcessor, @NonNull T> block
)

Starts a Perfetto trace processor shell server in http mode, loads a trace and executes the given block.

Public constructors

PerfettoTraceProcessor

Added in 1.2.0
public PerfettoTraceProcessor()

Public methods

loadTrace

Added in 1.2.0
public final @NonNull T <T extends Object> loadTrace(
    @NonNull PerfettoTrace trace,
    @ExtensionFunctionType @NonNull Function1<@NonNull PerfettoTraceProcessor.Session, @NonNull T> block
)

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

runServer

Added in 1.2.0
public static final @NonNull T <T extends Object> runServer(
    @ExtensionFunctionType @NonNull Function1<@NonNull PerfettoTraceProcessor, @NonNull T> block
)

Starts a Perfetto trace processor shell server in http mode, loads a trace and executes the given block. It stops the server after the block is complete

Uses a default timeout of 5 seconds

Parameters
@ExtensionFunctionType @NonNull Function1<@NonNull PerfettoTraceProcessor, @NonNull T> block

Command to execute using trace processor

runServer

public static final @NonNull T <T extends Object> runServer(
    @NonNull Duration timeout,
    @ExtensionFunctionType @NonNull Function1<@NonNull PerfettoTraceProcessor, @NonNull T> block
)

Starts a Perfetto trace processor shell server in http mode, loads a trace and executes the given block. It stops the server after the block is complete

Parameters
@NonNull Duration timeout

waiting for the server to start. If less or equal to zero use 5 seconds

@ExtensionFunctionType @NonNull Function1<@NonNull PerfettoTraceProcessor, @NonNull T> block

Command to execute using trace processor