public abstract class Tracer

A Tracer is the entry point for all Tracing APIs.

To obtain an instance of Tracer use TraceDriver.tracer.

Summary

Public constructors

Public methods
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.
abstract @NonNull EventMetadataCloseable
@DelicateTracingApi
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.
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.
abstract @NonNull EventMetadataCloseable
@DelicateTracingApi
beginSectionWithMetadata(
    @NonNull String category,
    @NonNull String name,
    PropagationToken token,
    boolean isRoot
)

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

Emits a zero duration section to the Trace with the provided category and name.
final void
@<Error class: unknown class>
instant(
    @NonNull String category,
    @NonNull String name,
    @NonNull Function1<@NonNull EventMetadata, Unit> metadataBlock
)

Emits a zero duration trace section.
final boolean

Is set to true if Tracing is enabled.
abstract @NonNull PropagationToken

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

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

This gives the ability to control how context propagation works for a androidx.tracing.Tracer.
final @NonNull T
@<Error class: unknown class>
<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 block as a named section of code in the trace with context propagation.
final @NonNull T
@<Error class: unknown class>
<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 block as a named section of code in the trace with context propagation.

Public constructors

Tracer

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

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
@NonNull String category

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

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

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.
boolean isRoot

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.
@NonNull Function1<@NonNull EventMetadata, Unit> metadataBlock

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

A 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
@NonNull String category

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

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

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.
boolean isRoot

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
@NonNull EventMetadataCloseable

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

beginSection

Added in 2.0.0-alpha01
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
@NonNull String category

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

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

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.
boolean isRoot

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.
@NonNull Function1<@NonNull EventMetadata, Unit> metadataBlock

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

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

beginSectionWithMetadata

Added in 2.0.0-alpha01
@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
@NonNull String category

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

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

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.
boolean isRoot

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
@NonNull EventMetadataCloseable

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

counter

Added in 2.0.0-alpha01
public abstract @NonNull Counter counter(@NonNull String category, @NonNull String name)
Returns
@NonNull Counter

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

instant

Added in 2.0.0-alpha01
@DelicateTracingApi
public abstract @NonNull EventMetadataCloseable instant(@NonNull String category, @NonNull String name)

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

instant

Added in 2.0.0-alpha01
@<Error class: unknown class>
public final void instant(
    @NonNull String category,
    @NonNull String name,
    @NonNull Function1<@NonNull EventMetadata, Unit> metadataBlock
)

Emits a zero duration trace section.

Parameters
@NonNull String category

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

The name of the code section to appear in the trace.
@NonNull Function1<@NonNull EventMetadata, Unit> metadataBlock

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

isEnabled

public final boolean isEnabled()

Is set to true if Tracing is enabled.

tokenForManualPropagation

Added in 2.0.0-alpha01
@ExperimentalContextPropagation
public abstract @NonNull PropagationToken tokenForManualPropagation()

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

tokenFromCoroutineContext

@DelicateTracingApi
public abstract @NonNull PropagationToken tokenFromCoroutineContext()

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

Added in 2.0.0-alpha01
@DelicateTracingApi
public abstract @NonNull PropagationToken tokenFromThreadContext()

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

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

Parameters
@NonNull String category

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

The name of the trace section.
PropagationToken token

The optional PropagationToken instance to use for context propagation. This defaults to the token returned by tokenFromThreadContext.
boolean isRoot

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.
@NonNull Function1<@NonNull EventMetadata, Unit> metadataBlock

The lambda that can be used to decorate the trace event with additional debug annotations.
@NonNull Function0<@NonNull T> block

The block of code being traced.
Returns
@NonNull T

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

traceCoroutine

@<Error class: unknown class>
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 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
@NonNull String category

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

The name of the trace section.
PropagationToken token

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.
boolean isRoot

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.
@NonNull Function1<@NonNull EventMetadata, Unit> metadataBlock

The lambda that can be used to decorate the trace event with additional debug annotations.
@NonNull SuspendFunction0<@NonNull T> block

The suspending block of code being traced.
Returns
@NonNull T

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