TraceProcessor  |  API reference  |  Android Developers (original) (raw)

• Cmn
  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:

• Trace Processor overview
• Common queries

Summary

Public companion functions

runServer

@ExperimentalTraceProcessorApi
@[](/reference/kotlin/[JVM root]/)
fun <T : Any?> runServer(
    serverLifecycleManager: ServerLifecycleManager,
    eventCallback: TraceProcessor.EventCallback,
    tracer: TraceProcessor.Tracer,
    timeoutMs: Long = DEFAULT_TIMEOUT_MS,
    block: TraceProcessor.() -> T
): T

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

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

startServer

@ExperimentalTraceProcessorApi
@[](/reference/kotlin/[JVM root]/)
fun startServer(
    serverLifecycleManager: ServerLifecycleManager,
    eventCallback: TraceProcessor.EventCallback,
    tracer: TraceProcessor.Tracer,
    timeoutMs: Long = DEFAULT_TIMEOUT_MS
): TraceProcessor.Handle

Starts a Perfetto trace processor shell server in http mode, and returns a [Handle](/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.Handle) which can be used to access and close the [TraceProcessor](/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor) server instance.

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

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

Public functions