A Tracer is the entry point for all Tracing APIs.

To obtain an instance of Tracer use TraceDriver.tracer.

Summary

Public constructors
Cmn

Public functions
suspend inline EventMetadataCloseable
beginCoroutineSection(
    category: String,
    name: String,
    token: PropagationToken?,
    isRoot: Boolean,
    crossinline metadataBlock: EventMetadata.() -> Unit
)

Writes a trace message indicating that a given suspending section of code has begun.
Cmn
abstract suspend EventMetadataCloseable
@DelicateTracingApi
beginCoroutineSectionWithMetadata(
    category: String,
    name: String,
    token: PropagationToken?,
    isRoot: Boolean
)

Writes a trace message indicating that a given suspending section of code has begun.
Cmn
inline AutoCloseable
beginSection(
    category: String,
    name: String,
    token: PropagationToken?,
    isRoot: Boolean,
    crossinline metadataBlock: EventMetadata.() -> Unit
)

Writes a trace message indicating that a given section of code has begun.
Cmn
abstract EventMetadataCloseable
@DelicateTracingApi
beginSectionWithMetadata(
    category: String,
    name: String,
    token: PropagationToken?,
    isRoot: Boolean
)

Writes a trace message indicating that a given section of code has begun.
Cmn
abstract Counter
counter(category: String, name: String)
Cmn
abstract EventMetadataCloseable

Emits a zero duration section to the Trace with the provided category and name.
Cmn
inline Unit
@<Error class: unknown class>
instant(
    category: String,
    name: String,
    crossinline metadataBlock: EventMetadata.() -> Unit
)

Emits a zero duration trace section.
Cmn
abstract PropagationToken

Creates a PropagationToken that can be used for manual context propagation in androidx.tracing.Tracer.
Cmn
abstract suspend PropagationToken

This gives the ability to control how context propagation works for a androidx.tracing.Tracer.
Cmn
abstract PropagationToken

This gives the ability to control how context propagation works for a androidx.tracing.Tracer.
Cmn
inline T
@<Error class: unknown class>
<T : Any?> trace(
    category: String,
    name: String,
    token: PropagationToken?,
    isRoot: Boolean,
    crossinline metadataBlock: EventMetadata.() -> Unit,
    crossinline block: () -> T
)

Traces the block as a named section of code in the trace with context propagation.
Cmn
suspend inline T
@<Error class: unknown class>
<T : Any?> traceCoroutine(
    category: String,
    name: String,
    token: PropagationToken?,
    isRoot: Boolean,
    crossinline metadataBlock: EventMetadata.() -> Unit,
    crossinline block: suspend () -> T
)

Traces the suspending block as a named section of code in the trace with context propagation.
Cmn

Public properties
Boolean

Is set to true if Tracing is enabled.
Cmn

Public constructors

Tracer

Cmn
Added in 2.0.0-alpha01
Tracer(@<Error class: unknown class> isEnabled: Boolean)

Public functions

beginCoroutineSection

Cmn 
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: String

The String category. It's useful to categorize TraceEvents, so that they can be filtered if necessary using the appropriate trace configuration.
name: String

The name of the code section to appear in the trace.
token: PropagationToken?

An optional PropagationToken that can be used for context propagation. The default implementation uses a list of Longs 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 Tracer obtains a token by calling tokenFromCoroutineContext.
isRoot: Boolean = false

A hint that tells the Tracer that this trace section is an entry point that all subsequent trace spans can be attributed to. Some Tracer implementations treat trace sections as a forest, and require that there is at least one top level root span.
crossinline metadataBlock: EventMetadata.() -> Unit

The lambda that can be used to decorate the trace event with additional debug annotations.
Returns
EventMetadataCloseable

A EventMetadataCloseable instance that can be used to add additional metadata and close the trace section.

beginCoroutineSectionWithMetadata

Cmn 
@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: String

The category that the trace section belongs to. Apps can potentially filter sections to the categories that they are interested in looking into.
name: String

The name of the code section to appear in the trace.
token: PropagationToken?

An optional PropagationToken that can be used for context propagation. The default implementation uses a list of Longs 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 Tracer obtains a token by calling tokenFromCoroutineContext.
isRoot: Boolean

A hint that tells the Tracer that this trace section is an entry point that all subsequent trace spans can be attributed to. Some Tracer implementations treat trace sections as a forest, and require that there is at least one top level root span.
Returns
EventMetadataCloseable

A EventMetadataCloseable instance that can be used to add additional metadata and close the trace section.

beginSection

Cmn
Added in 2.0.0-alpha01
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: String

The category that the trace section belongs to. Apps can potentially filter sections to the categories that they are interested in looking into.
name: String

The name of the code section to appear in the trace.
token: PropagationToken?

An optional PropagationToken that can be used for context propagation. The default implementation uses a list of Longs 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 Tracer implementation obtains the token by calling tokenFromThreadContext.
isRoot: Boolean = false

A hint that tells the Tracer that this trace section is an entry point that all subsequent trace spans can be attributed to. Some Tracer implementations treat trace sections as a forest, and require that there is at least one top level root span.
crossinline metadataBlock: EventMetadata.() -> Unit

The lambda that can be used to decorate the trace event with additional debug annotations.
Returns
AutoCloseable

A EventMetadataCloseable instance that can be used to add additional metadata and close the trace section.

beginSectionWithMetadata

Cmn
Added in 2.0.0-alpha01
@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: String

The category that the trace section belongs to. Apps can potentially filter sections to the categories that they are interested in looking into.
name: String

The name of the code section to appear in the trace.
token: PropagationToken?

An optional PropagationToken that can be used for context propagation. The default implementation uses a list of Longs 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 Tracer implementation obtains the token by calling tokenFromThreadContext.
isRoot: Boolean

A hint that tells the Tracer that this trace section is an entry point that all subsequent trace spans can be attributed to. Some Tracer implementations treat trace sections as a forest, and require that there is at least one top level root span.
Returns
EventMetadataCloseable

A EventMetadataCloseable instance that can be used to add additional metadata and close the trace section.

counter

Cmn
Added in 2.0.0-alpha01
abstract fun counter(category: String, name: String): Counter
Returns
Counter

The Counter instance for the provided category and name. This can be used to emit counter events.

instant

Cmn
Added in 2.0.0-alpha01
@DelicateTracingApi
abstract fun instant(category: String, name: String): EventMetadataCloseable

Emits a zero duration section to the Trace with the provided category and name.

instant

Cmn
Added in 2.0.0-alpha01
@<Error class: unknown class>
inline fun instant(
    category: String,
    name: String,
    crossinline metadataBlock: EventMetadata.() -> Unit = {}
): Unit

Emits a zero duration trace section.

Parameters
category: String

The category that the trace section belongs to. Apps can potentially filter sections to the categories that they are interested in looking into.
name: String

The name of the code section to appear in the trace.
crossinline metadataBlock: EventMetadata.() -> Unit = {}

The lambda that can be used to decorate the trace event with additional debug annotations.

tokenForManualPropagation

Cmn
Added in 2.0.0-alpha01
@ExperimentalContextPropagation
abstract fun tokenForManualPropagation(): PropagationToken

Creates a PropagationToken that can be used for manual context propagation in androidx.tracing.Tracer.

tokenFromCoroutineContext

Cmn 
@DelicateTracingApi
abstract suspend fun tokenFromCoroutineContext(): PropagationToken

This gives the ability to control how context propagation works for a androidx.tracing.Tracer.

Alternative implementations can choose to override this method to do something different. Examples include writing your own kotlin.coroutines.CoroutineContext.Element that bridges the gap with non-coroutine code by using ThreadLocals under the hood.

tokenFromThreadContext

Cmn
Added in 2.0.0-alpha01
@DelicateTracingApi
abstract fun tokenFromThreadContext(): PropagationToken

This gives the ability to control how context propagation works for a androidx.tracing.Tracer.

The default implementation does not support context propagation in non-suspending contexts by returning a PropagationUnsupportedToken instance. Alternative implementations can choose to override this method to do something different. Examples include using a ThreadLocal like primitive track of PropagationTokens across threads.

trace

Cmn
Added in 2.0.0-alpha01
@<Error class: unknown class>
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 block as a named section of code in the trace with context propagation.

Parameters
category: String

The String category. It's useful to categorize TraceEvents, so that they can be filtered if necessary using the appropriate trace configuration.
name: String

The name of the trace section.
token: PropagationToken? = null

The optional PropagationToken instance to use for context propagation. This defaults to the token returned by tokenFromThreadContext.
isRoot: Boolean = false

A hint that tells the Tracer that this trace section is an entry point that all subsequent trace spans can be attributed to. Some Tracer implementations treat trace sections as a forest, and require that there is at least one top level root span.
crossinline metadataBlock: EventMetadata.() -> Unit = {}

The lambda that can be used to decorate the trace event with additional debug annotations.
crossinline block: () -> T

The block of code being traced.
Returns
T

The AutoCloseable instance that can be used to close the trace section.

traceCoroutine

Cmn 
@<Error class: unknown class>
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 block as a named section of code in the trace with context propagation. The tokenFromCoroutineContext method is used to obtain the PropagationToken for context propagation.

Parameters
category: String

The String category. It's useful to categorize TraceEvents, so that they can be filtered if necessary using the appropriate trace configuration.
name: String

The name of the trace section.
token: PropagationToken? = null

An optional explicit 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 Tracer instance delegates to the implementation of tokenFromCoroutineContext.
isRoot: Boolean = false

A hint that tells the Tracer that this trace section is an entry point that all subsequent trace spans can be attributed to. Some Tracer implementations treat trace sections as a forest, and require that there is at least one top level root span.
crossinline metadataBlock: EventMetadata.() -> Unit = {}

The lambda that can be used to decorate the trace event with additional debug annotations.
crossinline block: suspend () -> T

The suspending block of code being traced.
Returns
T

The AutoCloseable instance that can be used to close the trace section.

Public properties

isEnabled

Cmn
Added in 2.0.0-alpha01
val isEnabled: Boolean

Is set to true if Tracing is enabled.