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

*** ** * ** ***


```
public abstract class Tracer
```

<br />

*** ** * ** ***

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

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

## Summary

| ### Nested types |
|---|
| `public static class https://developer.android.com/reference/androidx/tracing/Tracer.Companion` |

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

| ### Public methods |
|---|---|
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/tracing/EventMetadataCloseable` | `https://developer.android.com/reference/androidx/tracing/Tracer#beginCoroutineSection(kotlin.String,kotlin.String,androidx.tracing.PropagationToken,kotlin.Boolean,kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html category, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html name, https://developer.android.com/reference/androidx/tracing/PropagationToken token, boolean isRoot, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/tracing/EventMetadata, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> metadataBlock )` Writes a trace message indicating that a given suspending section of code has begun. |
| `abstract @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/tracing/EventMetadataCloseable` | `@https://developer.android.com/reference/androidx/tracing/DelicateTracingApi https://developer.android.com/reference/androidx/tracing/Tracer#beginCoroutineSectionWithMetadata(kotlin.String,kotlin.String,androidx.tracing.PropagationToken,kotlin.Boolean)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html category, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html name, https://developer.android.com/reference/androidx/tracing/PropagationToken token, boolean isRoot )` Writes a trace message indicating that a given suspending section of code has begun. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/AutoCloseable.html` | `https://developer.android.com/reference/androidx/tracing/Tracer#beginSection(kotlin.String,kotlin.String,androidx.tracing.PropagationToken,kotlin.Boolean,kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html category, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html name, https://developer.android.com/reference/androidx/tracing/PropagationToken token, boolean isRoot, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/tracing/EventMetadata, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> metadataBlock )` Writes a trace message indicating that a given section of code has begun. |
| `abstract @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/tracing/EventMetadataCloseable` | `@https://developer.android.com/reference/androidx/tracing/DelicateTracingApi https://developer.android.com/reference/androidx/tracing/Tracer#beginSectionWithMetadata(kotlin.String,kotlin.String,androidx.tracing.PropagationToken,kotlin.Boolean)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html category, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html name, https://developer.android.com/reference/androidx/tracing/PropagationToken token, boolean isRoot )` Writes a trace message indicating that a given section of code has begun. |
| `abstract @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/tracing/Counter` | `https://developer.android.com/reference/androidx/tracing/Tracer#counter(kotlin.String,kotlin.String)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html category, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html name)` |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/tracing/Tracer` | `https://developer.android.com/reference/androidx/tracing/Tracer#getGlobal()()` The Global tracer configured by the application. |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/tracing/Tracer` | `https://developer.android.com/reference/androidx/tracing/Tracer#getStubTracer()()` |
| `final void` | `https://developer.android.com/reference/androidx/tracing/Tracer#instant(kotlin.String,kotlin.String,androidx.tracing.PropagationToken,kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html category, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html name, https://developer.android.com/reference/androidx/tracing/PropagationToken token, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/tracing/EventMetadata, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> metadataBlock )` Emits a zero duration trace section. |
| `abstract boolean` | `https://developer.android.com/reference/androidx/tracing/Tracer#isCategoryEnabled(kotlin.String)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html category)` |
| `static final void` | `@https://developer.android.com/reference/androidx/tracing/DelicateTracingApi https://developer.android.com/reference/androidx/tracing/Tracer#setGlobalTracer(androidx.tracing.Tracer)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/tracing/Tracer tracer)` Registers the **global** `https://developer.android.com/reference/androidx/tracing/Tracer` instance. |
| `abstract @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/tracing/PropagationToken` | `@https://developer.android.com/reference/androidx/tracing/ExperimentalContextPropagation https://developer.android.com/reference/androidx/tracing/Tracer#tokenForManualPropagation(kotlin.collections.List)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Long.html> flowIds)` Creates a `https://developer.android.com/reference/androidx/tracing/PropagationToken` that can be used for manual context propagation in `https://developer.android.com/reference/androidx/tracing/Tracer`. |
| `abstract @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/tracing/PropagationToken` | `@https://developer.android.com/reference/androidx/tracing/DelicateTracingApi https://developer.android.com/reference/androidx/tracing/Tracer#tokenFromCoroutineContext()()` This gives the ability to control how context propagation works for a `https://developer.android.com/reference/androidx/tracing/Tracer`. |
| `abstract @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/tracing/PropagationToken` | `@https://developer.android.com/reference/androidx/tracing/DelicateTracingApi https://developer.android.com/reference/androidx/tracing/Tracer#tokenFromThreadContext()()` This gives the ability to control how context propagation works for a `https://developer.android.com/reference/androidx/tracing/Tracer`. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull T` | `<T extends https://developer.android.com/reference/java/lang/Object.html> https://developer.android.com/reference/androidx/tracing/Tracer#trace(kotlin.String,kotlin.String,androidx.tracing.PropagationToken,kotlin.Boolean,kotlin.Function1,kotlin.Function0)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html category, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html name, https://developer.android.com/reference/androidx/tracing/PropagationToken token, boolean isRoot, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/tracing/EventMetadata, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> metadataBlock, @https://developer.android.com/reference/androidx/annotation/NonNull Function0<@https://developer.android.com/reference/androidx/annotation/NonNull T> block )` Traces the `https://developer.android.com/reference/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. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull T` | `<T extends https://developer.android.com/reference/java/lang/Object.html> https://developer.android.com/reference/androidx/tracing/Tracer#traceCoroutine(kotlin.String,kotlin.String,androidx.tracing.PropagationToken,kotlin.Boolean,kotlin.Function1,kotlin.coroutines.SuspendFunction0)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html category, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html name, https://developer.android.com/reference/androidx/tracing/PropagationToken token, boolean isRoot, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/tracing/EventMetadata, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> metadataBlock, @https://developer.android.com/reference/androidx/annotation/NonNull SuspendFunction0<@https://developer.android.com/reference/androidx/annotation/NonNull T> block )` Traces the suspending `https://developer.android.com/reference/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. |
| `abstract @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/tracing/EventMetadataCloseable` | `@https://developer.android.com/reference/androidx/tracing/DelicateTracingApi https://developer.android.com/reference/androidx/tracing/Tracer#writeInstant(kotlin.String,kotlin.String,androidx.tracing.PropagationToken)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html category, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html name, https://developer.android.com/reference/androidx/tracing/PropagationToken token )` Writes a zero duration section to the Trace. |

| ### Extension functions |
|---|---|
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Void.html` | `https://developer.android.com/reference/androidx/tracing/Throwables.https://developer.android.com/reference/androidx/tracing/Tracer#(androidx.tracing.Tracer).recordExceptionAndThrow(kotlin.String,kotlin.String,kotlin.Throwable)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/tracing/Tracer receiver, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html category, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html name, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Throwable.html throwable )` Records an exceptional event in a trace. |

## Public constructors

### Tracer

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

```
public Tracer()
```

## Public methods

### beginCoroutineSection

```
public final @NonNull EventMetadataCloseable beginCoroutineSection(
    @NonNull String category,
    @NonNull String name,
    PropagationToken token,
    boolean isRoot,
    @NonNull Function1<@NonNull EventMetadata, Unit> metadataBlock
)
```

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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html category` | The `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` category. It's useful to categorize `https://developer.android.com/reference/androidx/tracing/TraceEvent`s, so that they can be filtered if necessary using the appropriate trace configuration. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html name` | The name of the code section to appear in the trace. |
| `https://developer.android.com/reference/androidx/tracing/PropagationToken token` | An optional `https://developer.android.com/reference/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/androidx/tracing/Tracer` obtains a token by calling `https://developer.android.com/reference/androidx/tracing/Tracer#tokenFromCoroutineContext()`. |
| `boolean isRoot` | A hint that tells the `https://developer.android.com/reference/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/androidx/tracing/Tracer` implementations treat trace sections as a forest, and require that there is at least one top level root span. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/tracing/EventMetadata, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> metadataBlock` | The lambda that can be used to decorate the trace event with additional debug annotations. |

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

### beginCoroutineSectionWithMetadata

```
@DelicateTracingApi
public abstract @NonNull EventMetadataCloseable beginCoroutineSectionWithMetadata(
    @NonNull String category,
    @NonNull String name,
    PropagationToken token,
    boolean isRoot
)
```

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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html category` | The category that the trace section belongs to. Apps can potentially filter sections to the categories that they are interested in looking into. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html name` | The name of the code section to appear in the trace. |
| `https://developer.android.com/reference/androidx/tracing/PropagationToken token` | An optional `https://developer.android.com/reference/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/androidx/tracing/Tracer` obtains a token by calling `https://developer.android.com/reference/androidx/tracing/Tracer#tokenFromCoroutineContext()`. |
| `boolean isRoot` | A hint that tells the `https://developer.android.com/reference/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/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/androidx/annotation/NonNull https://developer.android.com/reference/androidx/tracing/EventMetadataCloseable` | A `https://developer.android.com/reference/androidx/tracing/EventMetadataCloseable` instance that can be used to add additional metadata and close the trace section. |

### beginSection

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

```
public final @NonNull AutoCloseable beginSection(
    @NonNull String category,
    @NonNull String name,
    PropagationToken token,
    boolean isRoot,
    @NonNull Function1<@NonNull EventMetadata, Unit> metadataBlock
)
```

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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html category` | The category that the trace section belongs to. Apps can potentially filter sections to the categories that they are interested in looking into. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html name` | The name of the code section to appear in the trace. |
| `https://developer.android.com/reference/androidx/tracing/PropagationToken token` | An optional `https://developer.android.com/reference/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/androidx/tracing/Tracer` implementation obtains the token by calling `https://developer.android.com/reference/androidx/tracing/Tracer#tokenFromThreadContext()`. |
| `boolean isRoot` | A hint that tells the `https://developer.android.com/reference/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/androidx/tracing/Tracer` implementations treat trace sections as a forest, and require that there is at least one top level root span. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/tracing/EventMetadata, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> metadataBlock` | The lambda that can be used to decorate the trace event with additional debug annotations. |

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

### beginSectionWithMetadata

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

```
@DelicateTracingApi
public abstract @NonNull EventMetadataCloseable beginSectionWithMetadata(
    @NonNull String category,
    @NonNull String name,
    PropagationToken token,
    boolean isRoot
)
```

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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html category` | The category that the trace section belongs to. Apps can potentially filter sections to the categories that they are interested in looking into. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html name` | The name of the code section to appear in the trace. |
| `https://developer.android.com/reference/androidx/tracing/PropagationToken token` | An optional `https://developer.android.com/reference/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/androidx/tracing/Tracer` implementation obtains the token by calling `https://developer.android.com/reference/androidx/tracing/Tracer#tokenFromThreadContext()`. |
| `boolean isRoot` | A hint that tells the `https://developer.android.com/reference/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/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/androidx/annotation/NonNull https://developer.android.com/reference/androidx/tracing/EventMetadataCloseable` | A `https://developer.android.com/reference/androidx/tracing/EventMetadataCloseable` instance that can be used to add additional metadata and close the trace section. |

### counter

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

```
public abstract @NonNull Counter counter(@NonNull String category, @NonNull String name)
```

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

### getGlobal

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

```
public static final @NonNull Tracer getGlobal()
```

The Global tracer configured by the application.

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

The `https://developer.android.com/reference/androidx/tracing/Tracer.Companion#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/androidx/tracing/AbstractTraceDriver.Factory`, and constructs the instance. It then registers a global `https://developer.android.com/reference/androidx/tracing/Tracer` by calling `https://developer.android.com/reference/androidx/tracing/Tracer#setGlobalTracer(androidx.tracing.Tracer)`.

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

### getStubTracer

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

```
public static final @NonNull Tracer getStubTracer()
```

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/tracing/Tracer` | a `https://developer.android.com/reference/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. |

### instant

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

```
public final void instant(
    @NonNull String category,
    @NonNull String name,
    PropagationToken token,
    @NonNull Function1<@NonNull EventMetadata, Unit> metadataBlock
)
```

Emits a zero duration trace section.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html category` | The category that the trace section belongs to. Apps can potentially filter sections to the categories that they are interested in looking into. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html name` | The name of the code section to appear in the trace. |
| `https://developer.android.com/reference/androidx/tracing/PropagationToken token` | The optional `https://developer.android.com/reference/androidx/tracing/PropagationToken` instance to use for context propagation. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/tracing/EventMetadata, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> metadataBlock` | The lambda that can be used to decorate the trace event with additional debug annotations. |

### isCategoryEnabled

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

```
public abstract boolean isCategoryEnabled(@NonNull String category)
```

| Returns |
|---|---|
| `boolean` | `true` if the provided trace `https://developer.android.com/reference/androidx/tracing/Tracer#isCategoryEnabled(kotlin.String)` should be enabled. If `false` then trace events corresponding to the `https://developer.android.com/reference/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/androidx/tracing/Tracer` can emit trace events. |

### setGlobalTracer

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

```
@DelicateTracingApi
public static final void setGlobalTracer(@NonNull Tracer tracer)
```

Registers the **global** `https://developer.android.com/reference/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/androidx/tracing/AbstractTraceDriver`; typically during app startup.

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

### tokenForManualPropagation

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

```
@ExperimentalContextPropagation
public abstract @NonNull PropagationToken tokenForManualPropagation(@NonNull List<@NonNull Long> flowIds)
```

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

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Long.html> flowIds` | An optional list of `ids` that can be used to connect slices on different tracks. |

### tokenFromCoroutineContext

```
@DelicateTracingApi
public abstract @NonNull PropagationToken tokenFromCoroutineContext()
```

This gives the ability to control how context propagation works for a `https://developer.android.com/reference/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

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

```
@DelicateTracingApi
public abstract @NonNull PropagationToken tokenFromThreadContext()
```

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

The default implementation does not support context propagation in non-suspending contexts by returning a `https://developer.android.com/reference/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/androidx/tracing/PropagationToken`s across threads.

### trace

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

```
public final @NonNull T <T extends Object> trace(
    @NonNull String category,
    @NonNull String name,
    PropagationToken token,
    boolean isRoot,
    @NonNull Function1<@NonNull EventMetadata, Unit> metadataBlock,
    @NonNull Function0<@NonNull T> block
)
```

Traces the `https://developer.android.com/reference/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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html category` | The `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` category. It's useful to categorize `https://developer.android.com/reference/androidx/tracing/TraceEvent`s, so that they can be filtered if necessary using the appropriate trace configuration. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html name` | The name of the trace section. |
| `https://developer.android.com/reference/androidx/tracing/PropagationToken token` | The optional `https://developer.android.com/reference/androidx/tracing/PropagationToken` instance to use for context propagation. This defaults to the token returned by `https://developer.android.com/reference/androidx/tracing/Tracer#tokenFromThreadContext()`. |
| `boolean isRoot` | A hint that tells the `https://developer.android.com/reference/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/androidx/tracing/Tracer` implementations treat trace sections as a forest, and require that there is at least one top level root span. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/tracing/EventMetadata, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> metadataBlock` | The lambda that can be used to decorate the trace event with additional debug annotations. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function0<@https://developer.android.com/reference/androidx/annotation/NonNull T> block` | The `https://developer.android.com/reference/androidx/tracing/Tracer#trace(kotlin.String,kotlin.String,androidx.tracing.PropagationToken,kotlin.Boolean,kotlin.Function1,kotlin.Function0)` of code being traced. |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull T` | `https://developer.android.com/reference/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/androidx/tracing/Tracer#trace(kotlin.String,kotlin.String,androidx.tracing.PropagationToken,kotlin.Boolean,kotlin.Function1,kotlin.Function0)` being traced. |

### traceCoroutine

```
public final @NonNull T <T extends Object> traceCoroutine(
    @NonNull String category,
    @NonNull String name,
    PropagationToken token,
    boolean isRoot,
    @NonNull Function1<@NonNull EventMetadata, Unit> metadataBlock,
    @NonNull SuspendFunction0<@NonNull T> block
)
```

Traces the suspending `https://developer.android.com/reference/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/androidx/tracing/Tracer#tokenFromCoroutineContext()` method is used to obtain the `https://developer.android.com/reference/androidx/tracing/PropagationToken` for context propagation.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html category` | The `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` category. It's useful to categorize `https://developer.android.com/reference/androidx/tracing/TraceEvent`s, so that they can be filtered if necessary using the appropriate trace configuration. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html name` | The name of the trace section. |
| `https://developer.android.com/reference/androidx/tracing/PropagationToken token` | An optional explicit `https://developer.android.com/reference/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/androidx/tracing/Tracer` instance delegates to the implementation of `https://developer.android.com/reference/androidx/tracing/Tracer#tokenFromCoroutineContext()`. |
| `boolean isRoot` | A hint that tells the `https://developer.android.com/reference/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/androidx/tracing/Tracer` implementations treat trace sections as a forest, and require that there is at least one top level root span. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/tracing/EventMetadata, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> metadataBlock` | The lambda that can be used to decorate the trace event with additional debug annotations. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull SuspendFunction0<@https://developer.android.com/reference/androidx/annotation/NonNull T> block` | The suspending `https://developer.android.com/reference/androidx/tracing/Tracer#traceCoroutine(kotlin.String,kotlin.String,androidx.tracing.PropagationToken,kotlin.Boolean,kotlin.Function1,kotlin.coroutines.SuspendFunction0)` of code being traced. |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull T` | `https://developer.android.com/reference/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/androidx/tracing/Tracer#traceCoroutine(kotlin.String,kotlin.String,androidx.tracing.PropagationToken,kotlin.Boolean,kotlin.Function1,kotlin.coroutines.SuspendFunction0)` being traced. |

### writeInstant

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

```
@DelicateTracingApi
public abstract @NonNull EventMetadataCloseable writeInstant(
    @NonNull String category,
    @NonNull String name,
    PropagationToken token
)
```

Writes a zero duration section to the Trace.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html category` | The category that the trace section belongs to. Apps can potentially filter sections to the categories that they are interested in looking into. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html name` | The name of the code section to appear in the trace. |
| `https://developer.android.com/reference/androidx/tracing/PropagationToken token` | The optional `https://developer.android.com/reference/androidx/tracing/PropagationToken` instance to use for context propagation. |

## Extension functions

### Throwables.recordExceptionAndThrow

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)

```
public final @NonNull Void Throwables.recordExceptionAndThrow(
    @NonNull Tracer receiver,
    @NonNull String category,
    @NonNull String name,
    @NonNull Throwable throwable
)
```

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

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