# Tracer

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

*** ** * ** ***

Android/JVM
- android

  ```
  abstract class Tracer
  ```

*** ** * ** ***

A `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` is the entry point for all Tracing APIs.

To obtain an instance of `Tracer` use `https://developer.android.com/reference/kotlin/androidx/tracing/AbstractTraceDriver#tracer()`.

## Summary

| ### Public companion functions |
|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` | `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#getStubTracer()()` | android |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/VisibleForTesting https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#resetGlobalTracer()()` Resets the `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` for JVM and Android tests. | android |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/tracing/DelicateTracingApi https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#setGlobalTracer(androidx.tracing.Tracer)(tracer: https://developer.android.com/reference/kotlin/androidx/tracing/Tracer)` Registers the **global** `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` instance. | android |

| ### Public companion properties |
|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` | `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#global()` The Global tracer configured by the application. | android |

| ### Public constructors |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#Tracer()()` | android |

| ### Public functions |
|---|---|---|
| `suspend inline https://developer.android.com/reference/kotlin/androidx/tracing/EventMetadataCloseable` | `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#beginCoroutineSection(kotlin.String,kotlin.String,androidx.tracing.PropagationToken,kotlin.Boolean,kotlin.Function1)( category: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, token: https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken?, isRoot: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, crossinline metadataBlock: https://developer.android.com/reference/kotlin/androidx/tracing/EventMetadata.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html )` Writes a trace message indicating that a given suspending section of code has begun. | android |
| `abstract suspend https://developer.android.com/reference/kotlin/androidx/tracing/EventMetadataCloseable` | `@https://developer.android.com/reference/kotlin/androidx/tracing/DelicateTracingApi https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#beginCoroutineSectionWithMetadata(kotlin.String,kotlin.String,androidx.tracing.PropagationToken,kotlin.Boolean)( category: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, token: https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken?, isRoot: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html )` Writes a trace message indicating that a given suspending section of code has begun. | android |
| `inline https://developer.android.com/reference/java/lang/AutoCloseable.html` | `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#beginSection(kotlin.String,kotlin.String,androidx.tracing.PropagationToken,kotlin.Boolean,kotlin.Function1)( category: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, token: https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken?, isRoot: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, crossinline metadataBlock: https://developer.android.com/reference/kotlin/androidx/tracing/EventMetadata.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html )` Writes a trace message indicating that a given section of code has begun. | android |
| `abstract https://developer.android.com/reference/kotlin/androidx/tracing/EventMetadataCloseable` | `@https://developer.android.com/reference/kotlin/androidx/tracing/DelicateTracingApi https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#beginSectionWithMetadata(kotlin.String,kotlin.String,androidx.tracing.PropagationToken,kotlin.Boolean)( category: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, token: https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken?, isRoot: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html )` Writes a trace message indicating that a given section of code has begun. | android |
| `abstract https://developer.android.com/reference/kotlin/androidx/tracing/Counter` | `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#counter(kotlin.String,kotlin.String)(category: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)` | android |
| `inline https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#instant(kotlin.String,kotlin.String,androidx.tracing.PropagationToken,kotlin.Function1)( category: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, token: https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken?, crossinline metadataBlock: https://developer.android.com/reference/kotlin/androidx/tracing/EventMetadata.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html )` Emits a zero duration trace section. | android |
| `abstract https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#isCategoryEnabled(kotlin.String)(category: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)` | android |
| `abstract https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken` | `@https://developer.android.com/reference/kotlin/androidx/tracing/ExperimentalContextPropagation https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#tokenForManualPropagation(kotlin.collections.List)(flowIds: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html>)` Creates a `https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken` that can be used for manual context propagation in `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer`. | android |
| `abstract suspend https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken` | `@https://developer.android.com/reference/kotlin/androidx/tracing/DelicateTracingApi https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#tokenFromCoroutineContext()()` This gives the ability to control how context propagation works for a `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer`. | android |
| `abstract https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken` | `@https://developer.android.com/reference/kotlin/androidx/tracing/DelicateTracingApi https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#tokenFromThreadContext()()` This gives the ability to control how context propagation works for a `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer`. | android |
| `inline T` | `<T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?> https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#trace(kotlin.String,kotlin.String,androidx.tracing.PropagationToken,kotlin.Boolean,kotlin.Function1,kotlin.Function0)( category: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, token: https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken?, isRoot: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, crossinline metadataBlock: https://developer.android.com/reference/kotlin/androidx/tracing/EventMetadata.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html, crossinline block: () -> T )` Traces the `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#trace(kotlin.String,kotlin.String,androidx.tracing.PropagationToken,kotlin.Boolean,kotlin.Function1,kotlin.Function0)` as a named section of code in the trace with context propagation. | android |
| `suspend inline T` | `<T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?> https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#traceCoroutine(kotlin.String,kotlin.String,androidx.tracing.PropagationToken,kotlin.Boolean,kotlin.Function1,kotlin.coroutines.SuspendFunction0)( category: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, token: https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken?, isRoot: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, crossinline metadataBlock: https://developer.android.com/reference/kotlin/androidx/tracing/EventMetadata.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html, crossinline block: suspend () -> T )` Traces the suspending `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#traceCoroutine(kotlin.String,kotlin.String,androidx.tracing.PropagationToken,kotlin.Boolean,kotlin.Function1,kotlin.coroutines.SuspendFunction0)` as a named section of code in the trace with context propagation. | android |
| `abstract https://developer.android.com/reference/kotlin/androidx/tracing/EventMetadataCloseable` | `@https://developer.android.com/reference/kotlin/androidx/tracing/DelicateTracingApi https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#writeInstant(kotlin.String,kotlin.String,androidx.tracing.PropagationToken)(category: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, token: https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken?)` Writes a zero duration section to the Trace. | android |

| ### Extension functions |
|---|---|---|
| `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/Tracer#(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 |

## Public companion functions

### getStubTracer

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

```
fun getStubTracer(): Tracer
```

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` | a `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` instance that is a stub (does nothing). This is useful as a placeholder when you want to enable / disable tracing for the program. |

### resetGlobalTracer

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

```
@VisibleForTesting
fun resetGlobalTracer(): Unit
```

Resets the `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` for JVM and Android tests.

Note: This API should only be used in tests.

### setGlobalTracer

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

```
@DelicateTracingApi
fun setGlobalTracer(tracer: Tracer): Unit
```

Registers the **global** `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` instance.

This should only ever be done **once** per process lifecycle and by the application initializing the `https://developer.android.com/reference/kotlin/androidx/tracing/AbstractTraceDriver`; typically during app startup.

This should **never** be called by **libraries**.

## Public companion properties

### global

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

```
val global: Tracer
```

The Global tracer configured by the application.

This is the `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` that should be used by both application and library developers. You should always use `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#global()` and **not** cache references this field, given the `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` being used, is updated after the application is initialized.

The `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#global()` tracer is typically bootstrapped during process startup. When using `androidx.tracing:tracing-wire`, `androidx.tracing.profiler.ConnectedProfilerTracingInitializer` discovers the `https://developer.android.com/reference/kotlin/androidx/tracing/AbstractTraceDriver.Factory`, and constructs the instance. It then registers a global `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` by calling `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#setGlobalTracer(androidx.tracing.Tracer)`.

Otherwise, construct `https://developer.android.com/reference/kotlin/androidx/tracing/AbstractTraceDriver` during startup and register it via `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#setGlobalTracer(androidx.tracing.Tracer)` so other components can discover and use it.

## Public constructors

### Tracer

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

```
Tracer()
```

## Public functions

### beginCoroutineSection

android

```
suspend inline fun beginCoroutineSection(
    category: String,
    name: String,
    token: PropagationToken?,
    isRoot: Boolean = false,
    crossinline metadataBlock: EventMetadata.() -> Unit
): EventMetadataCloseable
```

Writes a trace message indicating that a given suspending section of code has begun.

Should be followed by a corresponding call to AutoCloseable.close returned by the call to `beginCoroutineSectionWithMetadata`. If the corresponding AutoCloseable.close is missing, the section will be present in the trace, but non-terminating (generally shown as fading out to the left).

| 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 code section to appear in the trace. |
| `token: https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken?` | An optional `https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken` that can be used for context propagation. The default implementation uses a list of `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html`s which will connect this trace section to other sections in the trace, potentially on different Tracks. The start and end of each trace `flow` (connection) between trace sections must share an ID, so each `Long` must be unique to each `flow` in the trace. When a `null` value is specified, the `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` obtains a token by calling `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#tokenFromCoroutineContext()`. |
| `isRoot: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = false` | A hint that tells the `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` that this trace section is an entry point that all subsequent trace spans can be attributed to. Some `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` implementations treat trace sections as a forest, and require that there is at least one top level root span. |
| `crossinline metadataBlock: https://developer.android.com/reference/kotlin/androidx/tracing/EventMetadata.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | The lambda that can be used to decorate the trace event with additional debug annotations. |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/tracing/EventMetadataCloseable` | A `https://developer.android.com/reference/kotlin/androidx/tracing/EventMetadataCloseable` instance that can be used to add additional metadata and close the trace section. |

### beginCoroutineSectionWithMetadata

android

```
@DelicateTracingApi
abstract suspend fun beginCoroutineSectionWithMetadata(
    category: String,
    name: String,
    token: PropagationToken?,
    isRoot: Boolean
): EventMetadataCloseable
```

Writes a trace message indicating that a given suspending section of code has begun.

Should be followed by a corresponding call to AutoCloseable.close returned by the call to `beginCoroutineSectionWithMetadata`. If the corresponding AutoCloseable.close is missing, the section will be present in the trace, but non-terminating (generally shown as fading out to the left).

| Parameters |
|---|---|
| `category: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The category that the trace section belongs to. Apps can potentially filter sections to the categories that they are interested in looking into. |
| `name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The name of the code section to appear in the trace. |
| `token: https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken?` | An optional `https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken` that can be used for context propagation. The default implementation uses a list of `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html`s which will connect this trace section to other sections in the trace, potentially on different Tracks. The start and end of each trace `flow` (connection) between trace sections must share an ID, so each `Long` must be unique to each `flow` in the trace. When a `null` value is specified, the `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` obtains a token by calling `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#tokenFromCoroutineContext()`. |
| `isRoot: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | A hint that tells the `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` that this trace section is an entry point that all subsequent trace spans can be attributed to. Some `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` implementations treat trace sections as a forest, and require that there is at least one top level root span. |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/tracing/EventMetadataCloseable` | A `https://developer.android.com/reference/kotlin/androidx/tracing/EventMetadataCloseable` instance that can be used to add additional metadata and close the trace section. |

### beginSection

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

```
inline fun beginSection(
    category: String,
    name: String,
    token: PropagationToken?,
    isRoot: Boolean = false,
    crossinline metadataBlock: EventMetadata.() -> Unit
): AutoCloseable
```

Writes a trace message indicating that a given section of code has begun.

Should be followed by a corresponding call to AutoCloseable.close returned by the call to `beginSection`. If the corresponding AutoCloseable.close is missing, the section will be present in the trace, but non-terminating (generally shown as fading out to the left).

| Parameters |
|---|---|
| `category: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The category that the trace section belongs to. Apps can potentially filter sections to the categories that they are interested in looking into. |
| `name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The name of the code section to appear in the trace. |
| `token: https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken?` | An optional `https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken` that can be used for context propagation. The default implementation uses a list of `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html`s which will connect this trace section to other sections in the trace, potentially on different Tracks. The start and end of each trace `flow` (connection) between trace sections must share an ID, so each `Long` must be unique to each `flow` in the trace. When a `null` value is specified, the `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` implementation obtains the token by calling `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#tokenFromThreadContext()`. |
| `isRoot: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = false` | A hint that tells the `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` that this trace section is an entry point that all subsequent trace spans can be attributed to. Some `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` implementations treat trace sections as a forest, and require that there is at least one top level root span. |
| `crossinline metadataBlock: https://developer.android.com/reference/kotlin/androidx/tracing/EventMetadata.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | The lambda that can be used to decorate the trace event with additional debug annotations. |

| Returns |
|---|---|
| `https://developer.android.com/reference/java/lang/AutoCloseable.html` | A `https://developer.android.com/reference/kotlin/androidx/tracing/EventMetadataCloseable` instance that can be used to add additional metadata and close the trace section. |

### beginSectionWithMetadata

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

```
@DelicateTracingApi
abstract fun beginSectionWithMetadata(
    category: String,
    name: String,
    token: PropagationToken?,
    isRoot: Boolean
): EventMetadataCloseable
```

Writes a trace message indicating that a given section of code has begun.

Should be followed by a corresponding call to AutoCloseable.close returned by the call to `beginSection`. If the corresponding AutoCloseable.close is missing, the section will be present in the trace, but non-terminating (generally shown as fading out to the left).

| Parameters |
|---|---|
| `category: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The category that the trace section belongs to. Apps can potentially filter sections to the categories that they are interested in looking into. |
| `name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The name of the code section to appear in the trace. |
| `token: https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken?` | An optional `https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken` that can be used for context propagation. The default implementation uses a list of `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html`s which will connect this trace section to other sections in the trace, potentially on different Tracks. The start and end of each trace `flow` (connection) between trace sections must share an ID, so each `Long` must be unique to each `flow` in the trace. When a `null` value is specified, the `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` implementation obtains the token by calling `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#tokenFromThreadContext()`. |
| `isRoot: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | A hint that tells the `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` that this trace section is an entry point that all subsequent trace spans can be attributed to. Some `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` implementations treat trace sections as a forest, and require that there is at least one top level root span. |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/tracing/EventMetadataCloseable` | A `https://developer.android.com/reference/kotlin/androidx/tracing/EventMetadataCloseable` instance that can be used to add additional metadata and close the trace section. |

### counter

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

```
abstract fun counter(category: String, name: String): Counter
```

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/tracing/Counter` | The `https://developer.android.com/reference/kotlin/androidx/tracing/Counter` instance for the provided `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#counter(kotlin.String,kotlin.String)` and `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#counter(kotlin.String,kotlin.String)`. This can be used to emit counter events. |

### instant

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

```
inline fun instant(
    category: String,
    name: String,
    token: PropagationToken? = null,
    crossinline metadataBlock: EventMetadata.() -> Unit = {}
): Unit
```

Emits a zero duration trace section.

| Parameters |
|---|---|
| `category: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The category that the trace section belongs to. Apps can potentially filter sections to the categories that they are interested in looking into. |
| `name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The name of the code section to appear in the trace. |
| `token: https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken? = null` | The optional `https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken` instance to use for context propagation. |
| `crossinline metadataBlock: https://developer.android.com/reference/kotlin/androidx/tracing/EventMetadata.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html = {}` | The lambda that can be used to decorate the trace event with additional debug annotations. |

### isCategoryEnabled

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

```
abstract fun isCategoryEnabled(category: String): Boolean
```

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `true` if the provided trace `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#isCategoryEnabled(kotlin.String)` should be enabled. If `false` then trace events corresponding to the `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#isCategoryEnabled(kotlin.String)` are dropped to reduce tracing overhead. This is particularly useful when you want to lower the overhead of trace events from uninteresting or noisy categories. Note:This method should be **extremely** low overhead given it's called every time a `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` can emit trace events. |

### tokenForManualPropagation

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

```
@ExperimentalContextPropagation
abstract fun tokenForManualPropagation(flowIds: List<Long> = listOf(monotonicId())): PropagationToken
```

Creates a `https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken` that can be used for manual context propagation in `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer`.

| Parameters |
|---|---|
| `flowIds: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html> = listOf(monotonicId())` | An optional list of `ids` that can be used to connect slices on different tracks. |

### tokenFromCoroutineContext

android

```
@DelicateTracingApi
abstract suspend fun tokenFromCoroutineContext(): PropagationToken
```

This gives the ability to control how context propagation works for a `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer`.

Alternative implementations can choose to override this method to do something different. Examples include writing your own `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.coroutines/-coroutine-context/-element/index.html` that bridges the gap with non-coroutine code by using `ThreadLocal`s under the hood.

### tokenFromThreadContext

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

```
@DelicateTracingApi
abstract fun tokenFromThreadContext(): PropagationToken
```

This gives the ability to control how context propagation works for a `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer`.

The default implementation does not support context propagation in non-suspending contexts by returning a `https://developer.android.com/reference/kotlin/androidx/tracing/PropagationUnsupportedToken` instance. Alternative implementations can choose to override this method to do something different. Examples include using a `ThreadLocal` like primitive track of `https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken`s across threads.

### trace

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

```
inline fun <T : Any?> trace(
    category: String,
    name: String,
    token: PropagationToken? = null,
    isRoot: Boolean = false,
    crossinline metadataBlock: EventMetadata.() -> Unit = {},
    crossinline block: () -> T
): T
```

Traces the `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#trace(kotlin.String,kotlin.String,androidx.tracing.PropagationToken,kotlin.Boolean,kotlin.Function1,kotlin.Function0)` as a named section of code in the trace with context propagation.

| 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. |
| `token: https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken? = null` | The optional `https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken` instance to use for context propagation. This defaults to the token returned by `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#tokenFromThreadContext()`. |
| `isRoot: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = false` | A hint that tells the `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` that this trace section is an entry point that all subsequent trace spans can be attributed to. Some `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` implementations treat trace sections as a forest, and require that there is at least one top level root span. |
| `crossinline metadataBlock: https://developer.android.com/reference/kotlin/androidx/tracing/EventMetadata.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html = {}` | The lambda that can be used to decorate the trace event with additional debug annotations. |
| `crossinline block: () -> T` | The `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#trace(kotlin.String,kotlin.String,androidx.tracing.PropagationToken,kotlin.Boolean,kotlin.Function1,kotlin.Function0)` of code being traced. |

| Returns |
|---|---|
| `T` | `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#trace(kotlin.String,kotlin.String,androidx.tracing.PropagationToken,kotlin.Boolean,kotlin.Function1,kotlin.Function0)` as returned by the `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#trace(kotlin.String,kotlin.String,androidx.tracing.PropagationToken,kotlin.Boolean,kotlin.Function1,kotlin.Function0)` being traced. |

### traceCoroutine

android

```
suspend inline fun <T : Any?> traceCoroutine(
    category: String,
    name: String,
    token: PropagationToken? = null,
    isRoot: Boolean = false,
    crossinline metadataBlock: EventMetadata.() -> Unit = {},
    crossinline block: suspend () -> T
): T
```

Traces the suspending `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#traceCoroutine(kotlin.String,kotlin.String,androidx.tracing.PropagationToken,kotlin.Boolean,kotlin.Function1,kotlin.coroutines.SuspendFunction0)` as a named section of code in the trace with context propagation. The `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#tokenFromCoroutineContext()` method is used to obtain the `https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken` for context propagation.

| 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. |
| `token: https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken? = null` | An optional explicit `https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken` instance that is intended to be used for manual context propagation. This might be useful in instances where the implementation of context propagation was to distinguish between job executions that are well scoped vs. fire and forget. When `null`, the `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` instance delegates to the implementation of `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#tokenFromCoroutineContext()`. |
| `isRoot: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = false` | A hint that tells the `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` that this trace section is an entry point that all subsequent trace spans can be attributed to. Some `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer` implementations treat trace sections as a forest, and require that there is at least one top level root span. |
| `crossinline metadataBlock: https://developer.android.com/reference/kotlin/androidx/tracing/EventMetadata.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html = {}` | The lambda that can be used to decorate the trace event with additional debug annotations. |
| `crossinline block: suspend () -> T` | The suspending `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#traceCoroutine(kotlin.String,kotlin.String,androidx.tracing.PropagationToken,kotlin.Boolean,kotlin.Function1,kotlin.coroutines.SuspendFunction0)` of code being traced. |

| Returns |
|---|---|
| `T` | `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#traceCoroutine(kotlin.String,kotlin.String,androidx.tracing.PropagationToken,kotlin.Boolean,kotlin.Function1,kotlin.coroutines.SuspendFunction0)` as returned by the suspending `https://developer.android.com/reference/kotlin/androidx/tracing/Tracer#traceCoroutine(kotlin.String,kotlin.String,androidx.tracing.PropagationToken,kotlin.Boolean,kotlin.Function1,kotlin.coroutines.SuspendFunction0)` being traced. |

### writeInstant

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

```
@DelicateTracingApi
abstract fun writeInstant(category: String, name: String, token: PropagationToken?): EventMetadataCloseable
```

Writes a zero duration section to the Trace.

| Parameters |
|---|---|
| `category: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The category that the trace section belongs to. Apps can potentially filter sections to the categories that they are interested in looking into. |
| `name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The name of the code section to appear in the trace. |
| `token: https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken?` | The optional `https://developer.android.com/reference/kotlin/androidx/tracing/PropagationToken` instance to use for context propagation. |

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

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