# TraceProcessor

Artifact: [androidx.benchmark:benchmark-traceprocessor](https://developer.android.com/jetpack/androidx/releases/benchmark) [View Source](https://cs.android.com/search?q=file:androidx/benchmark/traceprocessor/TraceProcessor.kt+class:androidx.benchmark.traceprocessor.TraceProcessor) Added in [1.4.0](https://developer.android.com/jetpack/androidx/releases/benchmark#1.4.0)

*** ** * ** ***

Android/JVM
- android

  ```
  class TraceProcessor
  ```

*** ** * ** ***

Kotlin API for [Perfetto Trace Processor](https://perfetto.dev/docs/analysis/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](https://ui.perfetto.dev), it can be queried from this API.

```kotlin
import androidx.benchmark.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:

```kotlin
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](https://perfetto.dev/docs/analysis/trace-processor)

- [Common queries](https://perfetto.dev/docs/analysis/common-queries)

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/PerfettoTrace` |   |

## Summary

| ### Nested types |
|---|
| `object https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.Companion` |
| `interface https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.EventCallback` |
| `object https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.EventCallback.Noop : https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.EventCallback` |
| `class https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.Handle : https://developer.android.com/reference/java/lang/AutoCloseable.html` |
| `class https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.Session` Handle to query sql data from a `https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/PerfettoTrace`. |
| `class https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.Session.Handle : https://developer.android.com/reference/java/lang/AutoCloseable.html` |
| `open class https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.Tracer` |

| ### Public companion functions |
|---|---|---|
| `T` | `@https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/ExperimentalTraceProcessorApi <T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?> https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor#runServer(androidx.benchmark.traceprocessor.ServerLifecycleManager,androidx.benchmark.traceprocessor.TraceProcessor.EventCallback,androidx.benchmark.traceprocessor.TraceProcessor.Tracer,kotlin.Long,kotlin.Function1)( serverLifecycleManager: https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/ServerLifecycleManager, eventCallback: https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.EventCallback, tracer: https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.Tracer, timeoutMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html, block: https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.() -> T )` Starts a Perfetto trace processor shell server in http mode, loads a trace and executes the given block. | android |
| `https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.Handle` | `@https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/ExperimentalTraceProcessorApi https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor#startServer(androidx.benchmark.traceprocessor.ServerLifecycleManager,androidx.benchmark.traceprocessor.TraceProcessor.EventCallback,androidx.benchmark.traceprocessor.TraceProcessor.Tracer,kotlin.Long)( serverLifecycleManager: https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/ServerLifecycleManager, eventCallback: https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.EventCallback, tracer: https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.Tracer, timeoutMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html )` Starts a Perfetto trace processor shell server in http mode, and returns a `https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.Handle` which can be used to access and close the `https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor` server instance. | android |

| ### Public functions |
|---|---|---|
| `T` | `<T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?> https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor#loadTrace(androidx.benchmark.traceprocessor.PerfettoTrace,kotlin.Function1)(trace: https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/PerfettoTrace, block: https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.Session.() -> T)` Loads a PerfettoTrace into the trace processor server to query data out of the trace. | android |
| `https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.Session.Handle` | `https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor#startSession(androidx.benchmark.traceprocessor.PerfettoTrace)(trace: https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/PerfettoTrace)` Loads a PerfettoTrace into the TraceProcessor server, and returns a `https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.Session.Handle` which can be used to access and close a `https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.Session`. | android |

## Public companion functions

### runServer

android Added in [1.4.0](https://developer.android.com/jetpack/androidx/releases/benchmark#1.4.0)

```
@ExperimentalTraceProcessorApi
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.

```kotlin
import androidx.benchmark.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
```

| Parameters |
|---|---|
| `serverLifecycleManager: https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/ServerLifecycleManager` | controls starting and stopping the TraceProcessor process. |
| `eventCallback: https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.EventCallback` | callback for events such as trace load failure. |
| `tracer: https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.Tracer` | used to trace begin and end of significant events within this managed run. |
| `timeoutMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html = DEFAULT_TIMEOUT_MS` | maximum duration in milliseconds for waiting for operations like loading the server, or querying a trace. |
| `block: https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.() -> T` | Command to execute using trace processor |

### startServer

android Added in [1.4.0](https://developer.android.com/jetpack/androidx/releases/benchmark#1.4.0)

```
@ExperimentalTraceProcessorApi
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 `https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.Handle` which can be used to access and close the `https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor` server instance.

```kotlin
import androidx.benchmark.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
```

| Parameters |
|---|---|
| `serverLifecycleManager: https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/ServerLifecycleManager` | controls starting and stopping the TraceProcessor process. |
| `eventCallback: https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.EventCallback` | callback for events such as trace load failure. |
| `tracer: https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.Tracer` | used to trace begin and end of significant events within this managed run. |
| `timeoutMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html = DEFAULT_TIMEOUT_MS` | maximum duration in milliseconds for waiting for operations like loading the server, or querying a trace. |

## Public functions

### loadTrace

android Added in [1.4.0](https://developer.android.com/jetpack/androidx/releases/benchmark#1.4.0)

```
fun <T : Any?> loadTrace(trace: PerfettoTrace, block: TraceProcessor.Session.() -> T): T
```

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

### startSession

android Added in [1.4.0](https://developer.android.com/jetpack/androidx/releases/benchmark#1.4.0)

```
fun startSession(trace: PerfettoTrace): TraceProcessor.Session.Handle
```

Loads a PerfettoTrace into the TraceProcessor server, and returns a `https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.Session.Handle` which can be used to access and close a `https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.Session`.