/
Android Studio Sign in

A Tracer is the entry point for all Tracing APIs.

To obtain an instance of Tracer use AbstractTraceDriver.tracer.

Summary

Public companion functions
Tracer
Cmn
Unit

Resets the global for JVM and Android tests.
Cmn
Unit

Registers the global Tracer instance.
Cmn

Public companion properties
Tracer

The Global tracer configured by the application.
Cmn

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
inline Unit
@<error>
instant(
    category: String,
    name: String,
    token: PropagationToken?,
    crossinline metadataBlock: EventMetadata.() -> Unit
)

Emits a zero duration trace section.
Cmn
abstract Boolean
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>
<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>
<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
abstract EventMetadataCloseable

Writes a zero duration section to the Trace.
Cmn

Extension functions
Nothing
Tracer.recordExceptionAndThrow(
    category: String,
    name: String,
    throwable: Throwable
)

Records an exceptional event in a trace.
Cmn

Public companion functions

getStubTracer

Cmn
Added in 2.0.0-beta01
@<error>
fun getStubTracer(): Tracer
Returns
Tracer

a 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

Cmn
Added in 2.0.0-beta01
@VisibleForTesting
fun resetGlobalTracer(): Unit

Resets the global for JVM and Android tests.

Note: This API should only be used in tests.

setGlobalTracer

Cmn
Added in 2.0.0-beta01
@<error>
@DelicateTracingApi
fun setGlobalTracer(tracer: Tracer): Unit

Registers the global Tracer instance.

This should only ever be done once per process lifecycle and by the application initializing the AbstractTraceDriver; typically during app startup.

This should never be called by libraries.

Public companion properties

global

Cmn
Added in 2.0.0-beta01
@<error>
val global: Tracer

The Global tracer configured by the application.

This is the Tracer that should be used by both application and library developers. You should always use Tracer.global and not cache references this field, given the Tracer being used, is updated after the application is initialized.

The global tracer is typically bootstrapped during process startup. When using androidx.tracing:tracing-wire, androidx.tracing.profiler.ConnectedProfilerTracingInitializer discovers the AbstractTraceDriver.Factory, and constructs the instance. It then registers a global Tracer by calling Tracer.setGlobalTracer.

Otherwise, construct AbstractTraceDriver during startup and register it via Tracer.setGlobalTracer so other components can discover and use it.

Public constructors

Tracer

Cmn
Added in 2.0.0-beta01
Tracer()

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-beta01
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-beta01
@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-beta01
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-beta01
@<error>
inline fun instant(
    category: String,
    name: String,
    token: PropagationToken? = null,
    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.
token: PropagationToken? = null

The optional PropagationToken instance to use for context propagation.
crossinline metadataBlock: EventMetadata.() -> Unit = {}

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

isCategoryEnabled

Cmn
Added in 2.0.0-beta01
abstract fun isCategoryEnabled(category: String): Boolean
Returns
Boolean

true if the provided trace category should be enabled.

If false then trace events corresponding to the category 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 Tracer can emit trace events.

tokenForManualPropagation

Cmn
Added in 2.0.0-beta01
@ExperimentalContextPropagation
abstract fun tokenForManualPropagation(flowIds: List<Long> = listOf(monotonicId())): PropagationToken

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

Parameters
flowIds: List<Long> = listOf(monotonicId())

An optional list of ids that can be used to connect slices on different tracks.

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-beta01
@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-beta01
@<error>
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

T as returned by the block being traced.

traceCoroutine

Cmn 
@<error>
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

T as returned by the suspending block being traced.

writeInstant

Cmn
Added in 2.0.0-beta01
@DelicateTracingApi
abstract fun writeInstant(category: String, name: String, token: PropagationToken?): EventMetadataCloseable

Writes a zero duration section to the Trace.

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?

The optional PropagationToken instance to use for context propagation.

Extension functions

Tracer.recordExceptionAndThrow

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

Records an exceptional event in a trace. This method rethrows the throwable after having extracting all metadata worth tracing.

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.
throwable: Throwable

The exception thrown by a block of code.
Morty Proxy This is a proxified and sanitized view of the page, visit original site.