# TraceProcessor.Companion

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.Companion) Added in [1.4.0](https://developer.android.com/jetpack/androidx/releases/benchmark#1.4.0)

*** ** * ** ***

Android/JVM
- android

  ```
  object TraceProcessor.Companion
  ```

*** ** * ** ***

## Summary

| ### Public 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 |

| ### Extension 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.Companion.https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.Companion#(androidx.benchmark.traceprocessor.TraceProcessor.Companion).runServer(kotlin.Long,kotlin.Function1)(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 TraceProcessor shell server in http mode. | 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.Companion.https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/TraceProcessor.Companion#(androidx.benchmark.traceprocessor.TraceProcessor.Companion).startServer(kotlin.Long)(timeoutMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html)` Starts a Perfetto TraceProcessor shell server in http mode. | android |

## Public 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. |

## Extension functions

### TraceProcessor.Companion.runServer

android Artifact: [androidx.benchmark:benchmark-common](https://developer.android.com/jetpack/androidx/releases/benchmark) [View Source](https://cs.android.com/search?q=file:androidx/benchmark/TraceProcessorExtensions.kt+function:runServer)

```
@ExperimentalTraceProcessorApi
fun <T : Any?> TraceProcessor.Companion.runServer(
    timeoutMs: Long = DEFAULT_TIMEOUT_MS,
    block: TraceProcessor.() -> T
): T
```

Starts a Perfetto TraceProcessor shell server in http mode.

The server is stopped after the block is complete.

```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 |
|---|---|
| `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 |

### TraceProcessor.Companion.startServer

android Artifact: [androidx.benchmark:benchmark-common](https://developer.android.com/jetpack/androidx/releases/benchmark) [View Source](https://cs.android.com/search?q=file:androidx/benchmark/TraceProcessorExtensions.kt+function:startServer)

```
@ExperimentalTraceProcessorApi
fun TraceProcessor.Companion.startServer(
    timeoutMs: Long = DEFAULT_TIMEOUT_MS
): TraceProcessor.Handle
```

Starts a Perfetto TraceProcessor shell server in http mode.

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