# androidx.tracing

*** ** * ** ***

Android/JVM

## Interfaces

|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/tracing/AbstractTraceDriver.Factory` | Provides the instance of `https://developer.android.com/reference/kotlin/androidx/tracing/AbstractTraceDriver` that can be used for in-process-tracing. | android |
| `https://developer.android.com/reference/kotlin/androidx/tracing/Counter` | Handle for emitting `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html` or `https://developer.android.com/reference/kotlin/androidx/tracing/Counter` counter event updates into a trace. | android |
| `https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken` | A token representing state carried forward for context propagation. | android |

## Classes

|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/tracing/AbstractTraceDriver` | The entry point for the tracing API. | android |
| `https://developer.android.com/reference/kotlin/androidx/tracing/AbstractTraceSink` | Receives `https://developer.android.com/reference/kotlin/androidx/tracing/PooledTracePacketArray`s from `https://developer.android.com/reference/kotlin/androidx/tracing/Track`s and asynchronously serializes them to a file or buffer, depending on implementation. | android |
| `https://developer.android.com/reference/kotlin/androidx/tracing/AtomicBoolean` |   | android |
| `https://developer.android.com/reference/kotlin/androidx/tracing/AtomicInteger` |   | android |
| `https://developer.android.com/reference/kotlin/androidx/tracing/AtomicLong` |   | android |
| `https://developer.android.com/reference/kotlin/androidx/tracing/AttributeEntry` | `https://developer.android.com/reference/kotlin/androidx/tracing/TraceEvent`s can contain trace attributes that apply to the entire trace. | android |
| `https://developer.android.com/reference/kotlin/androidx/tracing/EventMetadata` | Makes it possible to associate debug metadata \& categories to a `https://developer.android.com/reference/kotlin/androidx/tracing/TraceEvent`. | android |
| `https://developer.android.com/reference/kotlin/androidx/tracing/EventMetadataCloseable` | A holder for a `https://developer.android.com/reference/kotlin/androidx/tracing/EventMetadata` and the `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-auto-closeable/index.html`. | android |
| `https://developer.android.com/reference/kotlin/androidx/tracing/Frame` | `https://developer.android.com/reference/kotlin/androidx/tracing/TraceEvent`s can additionally contain callstack information. | android |
| `https://developer.android.com/reference/kotlin/androidx/tracing/MetadataEntry` | `https://developer.android.com/reference/kotlin/androidx/tracing/TraceEvent`s can contain metadata. | android |
| `https://developer.android.com/reference/kotlin/androidx/tracing/PlatformThreadContextElement` | We use the `https://developer.android.com/reference/kotlin/androidx/tracing/PlatformThreadContextElement` construct to know when a coroutine has suspended, and about to resume on a `Thread`. | android |
| `https://developer.android.com/reference/kotlin/androidx/tracing/Poolable` | Represents an object that can be reused using a `https://developer.android.com/reference/kotlin/androidx/tracing/Pool`. | android |
| `https://developer.android.com/reference/kotlin/androidx/tracing/PooledTracePacketArray` |   | android |
| `https://developer.android.com/reference/kotlin/androidx/tracing/TraceAttributes` | Makes it possible to associate key value pairs to be attached to a trace to provide additional context about any facet of the trace. | android |
| `https://developer.android.com/reference/kotlin/androidx/tracing/TraceEvent` | Mutable in-memory only representation a trace event, such as a slice start, slice end, or counter update. | android |
| `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` | A `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` is the entry point for all Tracing APIs. | android |
| `https://developer.android.com/reference/kotlin/androidx/tracing/TrackDescriptor` | Low level representation of a Track, written once to the Trace. | android |

## Objects

|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/tracing/PropagationUnsupportedToken` | The `https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken` instance that should be returned when context propagation is unsupported by the underlying `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer`. | android |
| `https://developer.android.com/reference/kotlin/androidx/tracing/Trace` |   | android |

## Annotations

|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/tracing/DelicateTracingApi` | Represents an API surface that is typically only useful for custom implementations of a `https://developer.android.com/reference/kotlin/androidx/tracing/AbstractTraceSink` or a `https://developer.android.com/reference/kotlin/androidx/tracing/Track`. | android |
| `https://developer.android.com/reference/kotlin/androidx/tracing/ExperimentalContextPropagation` | Represents an API surface that is typically only useful for custom context propagation. | android |

## Type aliases

|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/tracing/AtomicBoolean` |   | android |
| `https://developer.android.com/reference/kotlin/androidx/tracing/AtomicInteger` |   | android |
| `https://developer.android.com/reference/kotlin/androidx/tracing/AtomicLong` |   | android |

## Top-level functions summary

|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html` | `https://developer.android.com/reference/kotlin/androidx/tracing/package-summary#nanoTime()()` | android |
| `inline T` | `<T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?> https://developer.android.com/reference/kotlin/androidx/tracing/package-summary#trace(kotlin.String,kotlin.Function0)(label: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, block: () -> T)` Wrap the specified `https://developer.android.com/reference/kotlin/androidx/tracing/package-summary#trace(kotlin.String,kotlin.Function0)` in calls to `https://developer.android.com/reference/android/os/Trace.html#beginSection(java.lang.String)` (with the supplied `https://developer.android.com/reference/kotlin/androidx/tracing/package-summary#trace(kotlin.String,kotlin.Function0)`) and `https://developer.android.com/reference/android/os/Trace.html#endSection()`. | android |
| `inline T` | `<T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?> https://developer.android.com/reference/kotlin/androidx/tracing/package-summary#trace(kotlin.Function0,kotlin.Function0)(lazyLabel: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, block: () -> T)` Wrap the specified `https://developer.android.com/reference/kotlin/androidx/tracing/package-summary#trace(kotlin.Function0,kotlin.Function0)` in calls to `https://developer.android.com/reference/android/os/Trace.html#beginSection(java.lang.String)` (with a lazy-computed `https://developer.android.com/reference/kotlin/androidx/tracing/package-summary#trace(kotlin.Function0,kotlin.Function0)`, only if tracing is enabled - `https://developer.android.com/reference/android/os/Trace.html#isEnabled()`) and `https://developer.android.com/reference/android/os/Trace.html#endSection()`. | android |
| `inline T` | `<T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?> https://developer.android.com/reference/kotlin/androidx/tracing/package-summary#traceAsync(kotlin.Function0,kotlin.Function0,kotlin.Function0)( lazyMethodName: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, lazyCookie: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, block: () -> T )` Wrap the specified `https://developer.android.com/reference/kotlin/androidx/tracing/package-summary#traceAsync(kotlin.Function0,kotlin.Function0,kotlin.Function0)` in calls to `https://developer.android.com/reference/android/os/Trace.html#beginAsyncSection(java.lang.String, int)` and `https://developer.android.com/reference/android/os/Trace.html#endAsyncSection(java.lang.String, int)`, with a lazy-computed `https://developer.android.com/reference/kotlin/androidx/tracing/package-summary#traceAsync(kotlin.Function0,kotlin.Function0,kotlin.Function0)` and `https://developer.android.com/reference/kotlin/androidx/tracing/package-summary#traceAsync(kotlin.Function0,kotlin.Function0,kotlin.Function0)`, only if tracing is enabled - `https://developer.android.com/reference/android/os/Trace.html#isEnabled()`. | android |
| `suspend inline T` | `<T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?> https://developer.android.com/reference/kotlin/androidx/tracing/package-summary#traceAsync(kotlin.String,kotlin.Int,kotlin.coroutines.SuspendFunction0)( methodName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, cookie: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, crossinline block: suspend () -> T )` Wrap the specified `https://developer.android.com/reference/kotlin/androidx/tracing/package-summary#traceAsync(kotlin.String,kotlin.Int,kotlin.coroutines.SuspendFunction0)` in calls to `https://developer.android.com/reference/android/os/Trace.html#beginAsyncSection(java.lang.String, int)` (with the supplied `https://developer.android.com/reference/kotlin/androidx/tracing/package-summary#traceAsync(kotlin.String,kotlin.Int,kotlin.coroutines.SuspendFunction0)` and `https://developer.android.com/reference/kotlin/androidx/tracing/package-summary#traceAsync(kotlin.String,kotlin.Int,kotlin.coroutines.SuspendFunction0)`) and `https://developer.android.com/reference/android/os/Trace.html#endAsyncSection(java.lang.String, int)`. | android |

## Extension functions summary

|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-nothing/index.html` | `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer.https://developer.android.com/reference/kotlin/androidx/tracing/package-summary#(androidx.tracing.Tracer).recordExceptionAndThrow(kotlin.String,kotlin.String,kotlin.Throwable)( category: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, throwable: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-throwable/index.html )` Records an exceptional event in a trace. | android |

## Top-level functions

### nanoTime

android Artifact: [androidx.tracing:tracing](https://developer.android.com/jetpack/androidx/releases/tracing) [View Source](https://cs.android.com/search?q=file:androidx/tracing/ClockSource.+function:nanoTime)

```
fun nanoTime(): Long
```

### trace

android Artifact: [androidx.tracing:tracing](https://developer.android.com/jetpack/androidx/releases/tracing) [View Source](https://cs.android.com/search?q=file:androidx/tracing/Trace.android.kt+function:trace) Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/tracing#1.3.0)

```
inline fun <T : Any?> trace(label: String, block: () -> T): T
```

Wrap the specified `https://developer.android.com/reference/kotlin/androidx/tracing/package-summary#trace(kotlin.String,kotlin.Function0)` in calls to `https://developer.android.com/reference/android/os/Trace.html#beginSection(java.lang.String)` (with the supplied `https://developer.android.com/reference/kotlin/androidx/tracing/package-summary#trace(kotlin.String,kotlin.Function0)`) and `https://developer.android.com/reference/android/os/Trace.html#endSection()`.

| Parameters |
|---|---|
| `label: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | A name of the code section to appear in the trace. |
| `block: () -> T` | A block of code which is being traced. |

### trace

android Artifact: [androidx.tracing:tracing](https://developer.android.com/jetpack/androidx/releases/tracing) [View Source](https://cs.android.com/search?q=file:androidx/tracing/Trace.android.kt+function:trace) Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/tracing#1.3.0)

```
inline fun <T : Any?> trace(lazyLabel: () -> String, block: () -> T): T
```

Wrap the specified `https://developer.android.com/reference/kotlin/androidx/tracing/package-summary#trace(kotlin.Function0,kotlin.Function0)` in calls to `https://developer.android.com/reference/android/os/Trace.html#beginSection(java.lang.String)` (with a lazy-computed `https://developer.android.com/reference/kotlin/androidx/tracing/package-summary#trace(kotlin.Function0,kotlin.Function0)`, only if tracing is enabled - `https://developer.android.com/reference/android/os/Trace.html#isEnabled()`) and `https://developer.android.com/reference/android/os/Trace.html#endSection()`.

This variant allows you to build a dynamic label, but only when tracing is enabled, avoiding the cost of String construction otherwise.

| Parameters |
|---|---|
| `lazyLabel: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | A name of the code section to appear in the trace, computed lazily if needed. |
| `block: () -> T` | A block of code which is being traced. |

### traceAsync

android Artifact: [androidx.tracing:tracing](https://developer.android.com/jetpack/androidx/releases/tracing) [View Source](https://cs.android.com/search?q=file:androidx/tracing/Trace.android.kt+function:traceAsync) Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/tracing#1.3.0)

```
inline fun <T : Any?> traceAsync(
    lazyMethodName: () -> String,
    lazyCookie: () -> Int,
    block: () -> T
): T
```

Wrap the specified `https://developer.android.com/reference/kotlin/androidx/tracing/package-summary#traceAsync(kotlin.Function0,kotlin.Function0,kotlin.Function0)` in calls to `https://developer.android.com/reference/android/os/Trace.html#beginAsyncSection(java.lang.String, int)` and `https://developer.android.com/reference/android/os/Trace.html#endAsyncSection(java.lang.String, int)`, with a lazy-computed `https://developer.android.com/reference/kotlin/androidx/tracing/package-summary#traceAsync(kotlin.Function0,kotlin.Function0,kotlin.Function0)` and `https://developer.android.com/reference/kotlin/androidx/tracing/package-summary#traceAsync(kotlin.Function0,kotlin.Function0,kotlin.Function0)`, only if tracing is enabled - `https://developer.android.com/reference/android/os/Trace.html#isEnabled()`.

| Parameters |
|---|---|
| `lazyMethodName: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The method name to appear in the trace, computed lazily if needed. |
| `lazyCookie: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | Unique identifier for distinguishing simultaneous events, computed lazily if needed. |
| `block: () -> T` | a code block to be wrapped between `https://developer.android.com/reference/android/os/Trace.html#beginAsyncSection(java.lang.String, int)` and `https://developer.android.com/reference/android/os/Trace.html#endAsyncSection(java.lang.String, int)`. |

### traceAsync

android Artifact: [androidx.tracing:tracing](https://developer.android.com/jetpack/androidx/releases/tracing) [View Source](https://cs.android.com/search?q=file:androidx/tracing/Trace.android.kt+function:traceAsync)

```
suspend inline fun <T : Any?> traceAsync(
    methodName: String,
    cookie: Int,
    crossinline block: suspend () -> T
): T
```

Wrap the specified `https://developer.android.com/reference/kotlin/androidx/tracing/package-summary#traceAsync(kotlin.String,kotlin.Int,kotlin.coroutines.SuspendFunction0)` in calls to `https://developer.android.com/reference/android/os/Trace.html#beginAsyncSection(java.lang.String, int)` (with the supplied `https://developer.android.com/reference/kotlin/androidx/tracing/package-summary#traceAsync(kotlin.String,kotlin.Int,kotlin.coroutines.SuspendFunction0)` and `https://developer.android.com/reference/kotlin/androidx/tracing/package-summary#traceAsync(kotlin.String,kotlin.Int,kotlin.coroutines.SuspendFunction0)`) and `https://developer.android.com/reference/android/os/Trace.html#endAsyncSection(java.lang.String, int)`.

| Parameters |
|---|---|
| `methodName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The method name to appear in the trace. |
| `cookie: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | Unique identifier for distinguishing simultaneous events |
| `crossinline block: suspend () -> T` | A code block to be wrapped between `https://developer.android.com/reference/android/os/Trace.html#beginAsyncSection(java.lang.String, int)` and `https://developer.android.com/reference/android/os/Trace.html#endAsyncSection(java.lang.String, int)`. |

## Extension functions

### Tracer.recordExceptionAndThrow

android Artifact: [androidx.tracing:tracing](https://developer.android.com/jetpack/androidx/releases/tracing) [View Source](https://cs.android.com/search?q=file:androidx/tracing/Throwable.kt+function:recordExceptionAndThrow) Added in [2.0.5](https://developer.android.com/jetpack/androidx/releases/tracing#2.0.5)

```
fun Tracer.recordExceptionAndThrow(
    category: String,
    name: String,
    throwable: Throwable
): Nothing
```

Records an exceptional event in a trace. This method rethrows the `https://developer.android.com/reference/kotlin/androidx/tracing/package-summary#(androidx.tracing.Tracer).recordExceptionAndThrow(kotlin.String,kotlin.String,kotlin.Throwable)` after having extracting all metadata worth tracing.

| Parameters |
|---|---|
| `category: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` category. It's useful to categorize `https://developer.android.com/reference/kotlin/androidx/tracing/TraceEvent`s, so that they can be filtered if necessary using the appropriate trace configuration. |
| `name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The name of the trace section. |
| `throwable: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-throwable/index.html` | The exception thrown by a block of code. |