# PerfettoSdkHandshake

Artifact: [androidx.tracing:tracing-perfetto-handshake](https://developer.android.com/jetpack/androidx/releases/tracing) [View Source](https://cs.android.com/search?q=file:androidx/tracing/perfetto/handshake/PerfettoSdkHandshake.kt+class:androidx.tracing.perfetto.handshake.PerfettoSdkHandshake) Added in [1.0.1](https://developer.android.com/jetpack/androidx/releases/tracing#1.0.1)

*** ** * ** ***

<br />

```
class PerfettoSdkHandshake
```

<br />

*** ** * ** ***

Handshake implementation allowing to enable Perfetto SDK tracing in an app that enables it.

## Summary

| ### Nested types |
|---|
| `sealed class https://developer.android.com/reference/kotlin/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake.LibrarySource` Provides means to sideload Perfetto SDK native binaries |

| ### Public constructors |
|---|
| `https://developer.android.com/reference/kotlin/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#PerfettoSdkHandshake(kotlin.String,kotlin.Function1,kotlin.Function1)( targetPackage: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, parseJsonMap: (jsonString: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html>, executeShellCommand: (command: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html )` |

| ### Public functions |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/tracing/perfetto/handshake/protocol/Response` | `https://developer.android.com/reference/kotlin/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#disableTracingColdStart()()` Disables cold start tracing in the app if previously enabled by `https://developer.android.com/reference/kotlin/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#enableTracingColdStart(kotlin.Boolean,androidx.tracing.perfetto.handshake.PerfettoSdkHandshake.LibrarySource)`. |
| `https://developer.android.com/reference/kotlin/androidx/tracing/perfetto/handshake/protocol/Response` | `https://developer.android.com/reference/kotlin/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#enableTracingColdStart(kotlin.Boolean,androidx.tracing.perfetto.handshake.PerfettoSdkHandshake.LibrarySource)( persistent: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, librarySource: https://developer.android.com/reference/kotlin/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake.LibrarySource? )` Attempts to prepare cold startup tracing in the app. |
| `https://developer.android.com/reference/kotlin/androidx/tracing/perfetto/handshake/protocol/Response` | `https://developer.android.com/reference/kotlin/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#enableTracingImmediate(androidx.tracing.perfetto.handshake.PerfettoSdkHandshake.LibrarySource)( librarySource: https://developer.android.com/reference/kotlin/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake.LibrarySource? )` Attempts to enable tracing in the app. |

## Public constructors

### PerfettoSdkHandshake

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

```
PerfettoSdkHandshake(
    targetPackage: String,
    parseJsonMap: (jsonString: String) -> Map<String, String>,
    executeShellCommand: (command: String) -> String
)
```

| Parameters |
|---|---|
| `targetPackage: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | package name of the target app |
| `parseJsonMap: (jsonString: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html>` | function parsing a flat map in a JSON format into a `Map<String, String>` e.g. `"{ 'key 1': 'value 1', 'key 2': 'value 2' }"` -\>`mapOf("key 1" to "value 1", "key 2" to "value 2")` |
| `executeShellCommand: (command: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | function allowing to execute `adb shell` commands on the target device For error handling, note that `https://developer.android.com/reference/kotlin/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#parseJsonMap()` and `https://developer.android.com/reference/kotlin/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#executeShellCommand()` will be called on the same thread as `https://developer.android.com/reference/kotlin/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#enableTracingImmediate(androidx.tracing.perfetto.handshake.PerfettoSdkHandshake.LibrarySource)` and `https://developer.android.com/reference/kotlin/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#enableTracingColdStart(kotlin.Boolean,androidx.tracing.perfetto.handshake.PerfettoSdkHandshake.LibrarySource)`. |

## Public functions

### disableTracingColdStart

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

```
fun disableTracingColdStart(): Response
```

Disables cold start tracing in the app if previously enabled by `https://developer.android.com/reference/kotlin/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#enableTracingColdStart(kotlin.Boolean,androidx.tracing.perfetto.handshake.PerfettoSdkHandshake.LibrarySource)`.

No-op if cold start tracing was not enabled in the app, or if it was enabled in the non-`persistent` mode and the app has already been started at least once.

The function initially enables the app process (if not already enabled), but leaves it in a terminated state after executing.

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#enableTracingColdStart(kotlin.Boolean,androidx.tracing.perfetto.handshake.PerfettoSdkHandshake.LibrarySource)` |   |

### enableTracingColdStart

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

```
fun enableTracingColdStart(
    persistent: Boolean = false,
    librarySource: PerfettoSdkHandshake.LibrarySource? = null
): Response
```

Attempts to prepare cold startup tracing in the app.

Leaves the app process in a terminated state.

| Parameters |
|---|---|
| `persistent: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = false` | if set to true, cold start tracing mode is persisted between app runs and must be cleared using `https://developer.android.com/reference/kotlin/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#disableTracingColdStart()`. Otherwise, cold start tracing is enabled only for the first app start since enabling. While persistent mode reduces some overhead of setting up tracing, it recommended to use non-persistent mode as it does not pose the risk of leaving cold start tracing persistently enabled in case of a failure to clean-up with `https://developer.android.com/reference/kotlin/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#disableTracingColdStart()`. |
| `librarySource: https://developer.android.com/reference/kotlin/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake.LibrarySource? = null` | optional AAR or an APK containing `libtracing_perfetto.so` |

### enableTracingImmediate

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

```
fun enableTracingImmediate(
    librarySource: PerfettoSdkHandshake.LibrarySource? = null
): Response
```

Attempts to enable tracing in the app. It will wake up (or start) the app process, so it will act as warm/hot tracing. For cold tracing see `https://developer.android.com/reference/kotlin/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#enableTracingColdStart(kotlin.Boolean,androidx.tracing.perfetto.handshake.PerfettoSdkHandshake.LibrarySource)`

Note: if the app process is not running, it will be launched making the method a bad choice for cold tracing (use `https://developer.android.com/reference/kotlin/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#enableTracingColdStart(kotlin.Boolean,androidx.tracing.perfetto.handshake.PerfettoSdkHandshake.LibrarySource)` instead.

| Parameters |
|---|---|
| `librarySource: https://developer.android.com/reference/kotlin/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake.LibrarySource? = null` | optional AAR or an APK containing `libtracing_perfetto.so` |