# Trace

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

*** ** * ** ***

Android/JVM
- android

  ```
  object Trace
  ```

*** ** * ** ***

## Summary

| ### Public functions |
|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/tracing/Trace#beginAsyncSection(kotlin.String,kotlin.Int)(methodName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, cookie: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Writes a trace message to indicate that a given section of code has begun. | android |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/tracing/Trace#beginSection(kotlin.String)(label: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)` Writes a trace message to indicate that a given section of code has begun. | android |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/tracing/Trace#endAsyncSection(kotlin.String,kotlin.Int)(methodName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, cookie: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Writes a trace message to indicate that the current method has ended. | android |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/tracing/Trace#endSection()()` Writes a trace message to indicate that a given section of code has ended. | android |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/tracing/Trace#forceEnableAppTracing()()` Enables the app tracing tag in a non-debuggable process. | android |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/tracing/Trace#isEnabled()()` Checks whether or not tracing is currently enabled. | android |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/tracing/Trace#setCounter(kotlin.String,kotlin.Int)(counterName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, counterValue: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Writes trace message to indicate the value of a given counter. | android |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/RequiresApi(value = 29) https://developer.android.com/reference/kotlin/androidx/tracing/Trace#setCounter(kotlin.String,kotlin.Long)(counterName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, counterValue: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html)` Writes trace message to indicate the value of a given counter. | android |

## Public functions

### beginAsyncSection

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

```
fun beginAsyncSection(methodName: String, cookie: Int): Unit
```

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

Must be followed by a call to `https://developer.android.com/reference/kotlin/androidx/tracing/Trace#endAsyncSection(kotlin.String,kotlin.Int)` with the same methodName and cookie. Unlike `https://developer.android.com/reference/kotlin/androidx/tracing/Trace#beginSection(kotlin.String)` and `https://developer.android.com/reference/kotlin/androidx/tracing/Trace#endSection()`, asynchronous events do not need to be nested. The name and cookie used to begin an event must be used to end it.

The cookie must be unique to any overlapping events. If events don't overlap, you can simply always pass the same integer (e.g. `0`). If they do overlap, the cookie is used to disambiguate between overlapping events, like the following scenario:

```kotlin
[==========================]
          [=====================================]
                                     [====]
```

Without unique cookies, these start/stop timestamps could be misinterpreted by the trace display like the following, to show very different ranges:

```kotlin
[=========================================]
          [================]
                                     [==========]
```

| 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 with the same methodName. |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/tracing/Trace#endAsyncSection(kotlin.String,kotlin.Int)` |   |

### beginSection

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

```
fun beginSection(label: String): Unit
```

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

This call must be followed by a corresponding call to `https://developer.android.com/reference/kotlin/androidx/tracing/Trace#endSection()` on the same thread.

At this time the vertical bar character '\|', newline character '\\n', and null character '\\0' are used internally by the tracing mechanism. If sectionName contains these characters they will be replaced with a space character in the trace.

| Parameters |
|---|---|
| `label: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The name of the code section to appear in the trace. |

### endAsyncSection

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

```
fun endAsyncSection(methodName: String, cookie: Int): Unit
```

Writes a trace message to indicate that the current method has ended.

Must be called exactly once for each call to `https://developer.android.com/reference/kotlin/androidx/tracing/Trace#beginAsyncSection(kotlin.String,kotlin.Int)` using the same name and cookie.

| 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 with the same methodName. |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/tracing/Trace#beginAsyncSection(kotlin.String,kotlin.Int)` |   |

### endSection

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

```
fun endSection(): Unit
```

Writes a trace message to indicate that a given section of code has ended.

This call must be preceded by a corresponding call to `https://developer.android.com/reference/kotlin/androidx/tracing/Trace#beginSection(kotlin.String)`. Calling this method will mark the end of the most recently begun section of code, so care must be taken to ensure that beginSection / endSection pairs are properly nested and called from the same thread.

### forceEnableAppTracing

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

```
fun forceEnableAppTracing(): Unit
```

Enables the app tracing tag in a non-debuggable process.

Beginning in Android 12 (API 31), app tracing - custom tracing performed by app code via this class or android.os.Trace - is always enabled in all apps. Prior to this, app tracing was only enabled in debuggable apps (as well as profileable apps, on API 29/30).

Calling this method enables the app to record custom trace content without debuggable=true on any platform version that supports tracing. Tracing of non-debuggable apps is highly recommended, to ensure accurate performance measurements.

As app tracing is always enabled on Android 12 (API 31) and above, this does nothing after API 31.

### isEnabled

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

```
fun isEnabled(): Boolean
```

Checks whether or not tracing is currently enabled.

This is useful to avoid intermediate string creation for trace sections that require formatting. It is not necessary to guard all Trace method calls as they internally already check this. However, it is recommended to use this to prevent creating any temporary objects that would then be passed to those methods to reduce runtime cost when tracing isn't enabled.

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `true` if tracing is currently enabled, `false` otherwise. |

### setCounter

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

```
fun setCounter(counterName: String, counterValue: Int): Unit
```

Writes trace message to indicate the value of a given counter.

| Parameters |
|---|---|
| `counterName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The counter name to appear in the trace. |
| `counterValue: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | The counter value. |

### setCounter

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

```
@RequiresApi(value = 29)
fun setCounter(counterName: String, counterValue: Long): Unit
```

Writes trace message to indicate the value of a given counter.

| Parameters |
|---|---|
| `counterName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The counter name to appear in the trace. |
| `counterValue: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html` | The counter value. |