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

*** ** * ** ***

Android/JVM
- android

  ```
  object PerfettoTrace.Companion
  ```

*** ** * ** ***

## Summary

| ### Extension functions |
|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/benchmark/perfetto/ExperimentalPerfettoCaptureApi https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/PerfettoTrace.Companion.https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/PerfettoTrace.Companion#(androidx.benchmark.traceprocessor.PerfettoTrace.Companion).record(kotlin.String,kotlin.collections.List,kotlin.String,kotlin.Function1,kotlin.Function0)( fileLabel: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, appTagPackages: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html>, userspaceTracingPackage: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html?, traceCallback: ((https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/PerfettoTrace) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)?, block: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html )` Record a Perfetto System Trace for the specified `https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/package-summary#(androidx.benchmark.traceprocessor.PerfettoTrace.Companion).record(kotlin.String,kotlin.collections.List,kotlin.String,kotlin.Function1,kotlin.Function0)`. | android |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/benchmark/perfetto/ExperimentalPerfettoCaptureApi https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/PerfettoTrace.Companion.https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/PerfettoTrace.Companion#(androidx.benchmark.traceprocessor.PerfettoTrace.Companion).record(kotlin.String,androidx.benchmark.perfetto.PerfettoConfig,kotlin.String,kotlin.Function1,kotlin.Function0)( fileLabel: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, config: https://developer.android.com/reference/kotlin/androidx/benchmark/perfetto/PerfettoConfig, userspaceTracingPackage: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html?, traceCallback: ((https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/PerfettoTrace) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)?, block: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html )` Record a Perfetto System Trace for the specified `https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/package-summary#(androidx.benchmark.traceprocessor.PerfettoTrace.Companion).record(kotlin.String,androidx.benchmark.perfetto.PerfettoConfig,kotlin.String,kotlin.Function1,kotlin.Function0)`, with a fully custom Perfetto config, either text or binary. | android |

## Extension functions

### PerfettoTrace.Companion.record

android 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/PerfettoTrace.kt+function:record)

```
@ExperimentalPerfettoCaptureApi
fun PerfettoTrace.Companion.record(
    fileLabel: String,
    appTagPackages: List<String> = listOf(InstrumentationRegistry.getInstrumentation().targetContext.packageName),
    userspaceTracingPackage: String? = null,
    traceCallback: ((PerfettoTrace) -> Unit)? = null,
    block: () -> Unit
): Unit
```

Record a Perfetto System Trace for the specified `https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/package-summary#(androidx.benchmark.traceprocessor.PerfettoTrace.Companion).record(kotlin.String,kotlin.collections.List,kotlin.String,kotlin.Function1,kotlin.Function0)`.

```kotlin
PerfettoTrace.record("myTrace") {
    // content in here is traced to myTrace_<timestamp>.perfetto_trace
}
```

Reentrant Perfetto trace capture is not supported, so this API may not be combined with `BenchmarkRule`, `MacrobenchmarkRule`, or `PerfettoTraceRule`.

If the block throws, the trace is still captured and passed to `https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/package-summary#(androidx.benchmark.traceprocessor.PerfettoTrace.Companion).record(kotlin.String,kotlin.collections.List,kotlin.String,kotlin.Function1,kotlin.Function0)`.

### PerfettoTrace.Companion.record

android 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/PerfettoTrace.kt+function:record)

```
@ExperimentalPerfettoCaptureApi
fun PerfettoTrace.Companion.record(
    fileLabel: String,
    config: PerfettoConfig,
    userspaceTracingPackage: String? = null,
    traceCallback: ((PerfettoTrace) -> Unit)? = null,
    block: () -> Unit
): Unit
```

Record a Perfetto System Trace for the specified `https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/package-summary#(androidx.benchmark.traceprocessor.PerfettoTrace.Companion).record(kotlin.String,androidx.benchmark.perfetto.PerfettoConfig,kotlin.String,kotlin.Function1,kotlin.Function0)`, with a fully custom Perfetto config, either text or binary.

```kotlin
PerfettoTrace.record("myTrace", config = """...""") {
    // content in here is traced to myTrace_<timestamp>.perfetto_trace
}
```

Reentrant Perfetto trace capture is not supported, so this API may not be combined with `BenchmarkRule`, `MacrobenchmarkRule`, or `PerfettoTraceRule`.

If the block throws, the trace is still captured and passed to `https://developer.android.com/reference/kotlin/androidx/benchmark/traceprocessor/package-summary#(androidx.benchmark.traceprocessor.PerfettoTrace.Companion).record(kotlin.String,androidx.benchmark.perfetto.PerfettoConfig,kotlin.String,kotlin.Function1,kotlin.Function0)`.