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

*** ** * ** ***


```
public static class TraceProcessor.Companion
```

<br />

*** ** * ** ***

## Summary

| ### Public methods |
|---|---|
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull T` | `@https://developer.android.com/reference/androidx/benchmark/traceprocessor/ExperimentalTraceProcessorApi <T extends https://developer.android.com/reference/java/lang/Object.html> https://developer.android.com/reference/androidx/benchmark/traceprocessor/TraceProcessor#runServer(androidx.benchmark.traceprocessor.ServerLifecycleManager,androidx.benchmark.traceprocessor.TraceProcessor.EventCallback,androidx.benchmark.traceprocessor.TraceProcessor.Tracer,kotlin.Long,kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/traceprocessor/ServerLifecycleManager serverLifecycleManager, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/traceprocessor/TraceProcessor.EventCallback eventCallback, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/traceprocessor/TraceProcessor.Tracer tracer, long timeoutMs, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/traceprocessor/TraceProcessor, @https://developer.android.com/reference/androidx/annotation/NonNull T> block )` Starts a Perfetto trace processor shell server in http mode, loads a trace and executes the given block. |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/traceprocessor/TraceProcessor.Handle` | `@https://developer.android.com/reference/androidx/benchmark/traceprocessor/ExperimentalTraceProcessorApi https://developer.android.com/reference/androidx/benchmark/traceprocessor/TraceProcessor#startServer(androidx.benchmark.traceprocessor.ServerLifecycleManager,androidx.benchmark.traceprocessor.TraceProcessor.EventCallback,androidx.benchmark.traceprocessor.TraceProcessor.Tracer,kotlin.Long)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/traceprocessor/ServerLifecycleManager serverLifecycleManager, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/traceprocessor/TraceProcessor.EventCallback eventCallback, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/traceprocessor/TraceProcessor.Tracer tracer, long timeoutMs )` Starts a Perfetto trace processor shell server in http mode, and returns a `https://developer.android.com/reference/androidx/benchmark/traceprocessor/TraceProcessor.Handle` which can be used to access and close the `https://developer.android.com/reference/androidx/benchmark/traceprocessor/TraceProcessor` server instance. |

| ### Extension functions |
|---|---|
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull T` | `@https://developer.android.com/reference/androidx/benchmark/traceprocessor/ExperimentalTraceProcessorApi <T extends https://developer.android.com/reference/java/lang/Object.html> https://developer.android.com/reference/androidx/benchmark/traceprocessor/TraceProcessorExtensions.https://developer.android.com/reference/androidx/benchmark/traceprocessor/TraceProcessor.Companion#(androidx.benchmark.traceprocessor.TraceProcessor.Companion).runServer(kotlin.Long,kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/traceprocessor/TraceProcessor.Companion receiver, long timeoutMs, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/traceprocessor/TraceProcessor, @https://developer.android.com/reference/androidx/annotation/NonNull T> block )` Starts a Perfetto TraceProcessor shell server in http mode. |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/traceprocessor/TraceProcessor.Handle` | `@https://developer.android.com/reference/androidx/benchmark/traceprocessor/ExperimentalTraceProcessorApi https://developer.android.com/reference/androidx/benchmark/traceprocessor/TraceProcessorExtensions.https://developer.android.com/reference/androidx/benchmark/traceprocessor/TraceProcessor.Companion#(androidx.benchmark.traceprocessor.TraceProcessor.Companion).startServer(kotlin.Long)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/traceprocessor/TraceProcessor.Companion receiver, long timeoutMs )` Starts a Perfetto TraceProcessor shell server in http mode. |

## Public methods

### runServer

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

```
@ExperimentalTraceProcessorApi
public static final @NonNull T <T extends Object> runServer(
    @NonNull ServerLifecycleManager serverLifecycleManager,
    @NonNull TraceProcessor.EventCallback eventCallback,
    @NonNull TraceProcessor.Tracer tracer,
    long timeoutMs,
    @NonNull Function1<@NonNull TraceProcessor, @NonNull T> block
)
```

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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/traceprocessor/ServerLifecycleManager serverLifecycleManager` | controls starting and stopping the TraceProcessor process. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/traceprocessor/TraceProcessor.EventCallback eventCallback` | callback for events such as trace load failure. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/traceprocessor/TraceProcessor.Tracer tracer` | used to trace begin and end of significant events within this managed run. |
| `long timeoutMs` | maximum duration in milliseconds for waiting for operations like loading the server, or querying a trace. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/traceprocessor/TraceProcessor, @https://developer.android.com/reference/androidx/annotation/NonNull T> block` | Command to execute using trace processor |

### startServer

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

```
@ExperimentalTraceProcessorApi
public static final @NonNull TraceProcessor.Handle startServer(
    @NonNull ServerLifecycleManager serverLifecycleManager,
    @NonNull TraceProcessor.EventCallback eventCallback,
    @NonNull TraceProcessor.Tracer tracer,
    long timeoutMs
)
```

Starts a Perfetto trace processor shell server in http mode, and returns a `https://developer.android.com/reference/androidx/benchmark/traceprocessor/TraceProcessor.Handle` which can be used to access and close the `https://developer.android.com/reference/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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/traceprocessor/ServerLifecycleManager serverLifecycleManager` | controls starting and stopping the TraceProcessor process. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/traceprocessor/TraceProcessor.EventCallback eventCallback` | callback for events such as trace load failure. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/traceprocessor/TraceProcessor.Tracer tracer` | used to trace begin and end of significant events within this managed run. |
| `long timeoutMs` | maximum duration in milliseconds for waiting for operations like loading the server, or querying a trace. |

## Extension functions

### TraceProcessorExtensions.runServer

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
public static final @NonNull T <T extends Object> TraceProcessorExtensions.runServer(
    @NonNull TraceProcessor.Companion receiver,
    long timeoutMs,
    @NonNull Function1<@NonNull TraceProcessor, @NonNull T> block
)
```

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 |
|---|---|
| `long timeoutMs` | maximum duration in milliseconds for waiting for operations like loading the server, or querying a trace. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/benchmark/traceprocessor/TraceProcessor, @https://developer.android.com/reference/androidx/annotation/NonNull T> block` | Command to execute using trace processor |

### TraceProcessorExtensions.startServer

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
public static final @NonNull TraceProcessor.Handle TraceProcessorExtensions.startServer(
    @NonNull TraceProcessor.Companion receiver,
    long timeoutMs
)
```

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 |
|---|---|
| `long timeoutMs` | maximum duration in milliseconds for waiting for operations like loading the server, or querying a trace. |