TraceEvent

@DelicateTracingApi
public final class TraceEvent

Mutable in-memory only representation a trace event, such as a slice start, slice end, or counter update.

This structure is optimized for performance, with the expectation that these are created by a trace event, and passed to a background thread to be serialized. Mutability (and thus reuse) is an important component of this.

Code outside of tracing-driver implementation should only ever consume these objects, not produce them.

Summary

Public constructors

Public methods
final @NonNull List<@NonNull String>

The categories that this Trace Event belongs to.
final Long

The optional correlation id associated with the event.
final String

The optional correlation id as String that is associated with the event.
final Double

Value of the trace event if the event type is TRACE_EVENT_TYPE_COUNTER.
final Long

Value of the trace event if the event type is TRACE_EVENT_TYPE_COUNTER.
final @NonNull List<@NonNull Long>

List of trace flows associated with this event.
final @NonNull List<@NonNull Frame>

A list of call stack frames that can be associated to the androidx.tracing.TraceEvent.
final int

Keeping track of the index separately for categories, because the MutableList is pre-allocated with sentinel objects for performance reasons.
final int

Keeping track of the index separately for frames, because the MutableList is pre-allocated with sentinel objects for performance reasons.
final int

Keeping track of the index separately, because the MutableList is pre-allocated with sentinel objects for performance reasons.
final @NonNull List<@NonNull MetadataEntry>

The list of debug annotations associated with a slice
final String

Name of the trace event - null if the event type is TRACE_EVENT_TYPE_COUNTER.
final @NonNull String

The primary category that this trace event belongs to.
final long

Timestamp in nanoseconds of the trace event.
final TrackDescriptor

If not null, this TraceEvent initializes a track, and the TrackDescriptor defines its properties.
final long

Set to the value of the containing Track's Track.uuid.
final int

Must be one of TRACE_EVENT_TYPE_UNDEFINED, TRACE_EVENT_TYPE_INSTANT, TRACE_EVENT_TYPE_BEGIN, TRACE_EVENT_TYPE_END, TRACE_EVENT_TYPE_COUNTER
final void
final void

The categories that this Trace Event belongs to.
final void
setCorrelationId(Long correlationId)

The optional correlation id associated with the event.
final void
setCorrelationIdString(String correlationIdString)

The optional correlation id as String that is associated with the event.
final void
setCounterDoubleValue(Double counterDoubleValue)

Value of the trace event if the event type is TRACE_EVENT_TYPE_COUNTER.
final void
setCounterLongValue(Long counterLongValue)

Value of the trace event if the event type is TRACE_EVENT_TYPE_COUNTER.
final void

List of trace flows associated with this event.
final void

A list of call stack frames that can be associated to the androidx.tracing.TraceEvent.
final void
setLastCategoryIndex(int lastCategoryIndex)

Keeping track of the index separately for categories, because the MutableList is pre-allocated with sentinel objects for performance reasons.
final void
setLastFrameIndex(int lastFrameIndex)

Keeping track of the index separately for frames, because the MutableList is pre-allocated with sentinel objects for performance reasons.
final void
setLastMetadataEntryIndex(int lastMetadataEntryIndex)

Keeping track of the index separately, because the MutableList is pre-allocated with sentinel objects for performance reasons.
final void

The list of debug annotations associated with a slice
final void

Name of the trace event - null if the event type is TRACE_EVENT_TYPE_COUNTER.
final void
setPrimaryCategory(@NonNull String primaryCategory)

The primary category that this trace event belongs to.
final void
setTimestamp(long timestamp)

Timestamp in nanoseconds of the trace event.
final void

If not null, this TraceEvent initializes a track, and the TrackDescriptor defines its properties.
final void
setTrackUuid(long trackUuid)

Set to the value of the containing Track's Track.uuid.
final void
setType(int type)

Must be one of TRACE_EVENT_TYPE_UNDEFINED, TRACE_EVENT_TYPE_INSTANT, TRACE_EVENT_TYPE_BEGIN, TRACE_EVENT_TYPE_END, TRACE_EVENT_TYPE_COUNTER

Public constructors

TraceEvent

Added in 2.0.0-alpha01
public TraceEvent()

Public methods

getCategories

public final @NonNull List<@NonNull String> getCategories()

The categories that this Trace Event belongs to.

getCorrelationId

public final Long getCorrelationId()

The optional correlation id associated with the event.

getCorrelationIdString

public final String getCorrelationIdString()

The optional correlation id as String that is associated with the event.

getCounterDoubleValue

public final Double getCounterDoubleValue()

Value of the trace event if the event type is TRACE_EVENT_TYPE_COUNTER.

Note that only one of counterDoubleValue and counterLongValue may be set.

getCounterLongValue

public final Long getCounterLongValue()

Value of the trace event if the event type is TRACE_EVENT_TYPE_COUNTER.

Note that only one of counterDoubleValue and counterLongValue may be set.

getFlowIds

public final @NonNull List<@NonNull Long> getFlowIds()

List of trace flows associated with this event.

getFrames

public final @NonNull List<@NonNull Frame> getFrames()

A list of call stack frames that can be associated to the androidx.tracing.TraceEvent.

getLastCategoryIndex

public final int getLastCategoryIndex()

Keeping track of the index separately for categories, because the MutableList is pre-allocated with sentinel objects for performance reasons. This index can be used to determine the true size of the categories MutableList.

getLastFrameIndex

public final int getLastFrameIndex()

Keeping track of the index separately for frames, because the MutableList is pre-allocated with sentinel objects for performance reasons. This index can be used to determine the true size of the frames MutableList.

getLastMetadataEntryIndex

public final int getLastMetadataEntryIndex()

Keeping track of the index separately, because the MutableList is pre-allocated with sentinel objects for performance reasons. This index can be used to determine the true size of the metadataEntries MutableList.

getMetadataEntries

public final @NonNull List<@NonNull MetadataEntry> getMetadataEntries()

The list of debug annotations associated with a slice

getName

public final String getName()

Name of the trace event - null if the event type is TRACE_EVENT_TYPE_COUNTER.

getPrimaryCategory

public final @NonNull String getPrimaryCategory()

The primary category that this trace event belongs to.

getTimestamp

public final long getTimestamp()

Timestamp in nanoseconds of the trace event.

getTrackDescriptor

public final TrackDescriptor getTrackDescriptor()

If not null, this TraceEvent initializes a track, and the TrackDescriptor defines its properties.

getTrackUuid

public final long getTrackUuid()

Set to the value of the containing Track's Track.uuid.

getType

public final int getType()

Must be one of TRACE_EVENT_TYPE_UNDEFINED, TRACE_EVENT_TYPE_INSTANT, TRACE_EVENT_TYPE_BEGIN, TRACE_EVENT_TYPE_END, TRACE_EVENT_TYPE_COUNTER

reset

Added in 2.0.0-alpha01
public final void reset()

setCategories

public final void setCategories(@NonNull List<@NonNull String> categories)

The categories that this Trace Event belongs to.

setCorrelationId

public final void setCorrelationId(Long correlationId)

The optional correlation id associated with the event.

setCorrelationIdString

public final void setCorrelationIdString(String correlationIdString)

The optional correlation id as String that is associated with the event.

setCounterDoubleValue

public final void setCounterDoubleValue(Double counterDoubleValue)

Value of the trace event if the event type is TRACE_EVENT_TYPE_COUNTER.

Note that only one of counterDoubleValue and counterLongValue may be set.

setCounterLongValue

public final void setCounterLongValue(Long counterLongValue)

Value of the trace event if the event type is TRACE_EVENT_TYPE_COUNTER.

Note that only one of counterDoubleValue and counterLongValue may be set.

setFlowIds

public final void setFlowIds(@NonNull List<@NonNull Long> flowIds)

List of trace flows associated with this event.

setFrames

public final void setFrames(@NonNull List<@NonNull Frame> frames)

A list of call stack frames that can be associated to the androidx.tracing.TraceEvent.

setLastCategoryIndex

public final void setLastCategoryIndex(int lastCategoryIndex)

Keeping track of the index separately for categories, because the MutableList is pre-allocated with sentinel objects for performance reasons. This index can be used to determine the true size of the categories MutableList.

setLastFrameIndex

public final void setLastFrameIndex(int lastFrameIndex)

Keeping track of the index separately for frames, because the MutableList is pre-allocated with sentinel objects for performance reasons. This index can be used to determine the true size of the frames MutableList.

setLastMetadataEntryIndex

public final void setLastMetadataEntryIndex(int lastMetadataEntryIndex)

Keeping track of the index separately, because the MutableList is pre-allocated with sentinel objects for performance reasons. This index can be used to determine the true size of the metadataEntries MutableList.

setMetadataEntries

public final void setMetadataEntries(@NonNull List<@NonNull MetadataEntry> metadataEntries)

The list of debug annotations associated with a slice

setName

public final void setName(String name)

Name of the trace event - null if the event type is TRACE_EVENT_TYPE_COUNTER.

setPrimaryCategory

public final void setPrimaryCategory(@NonNull String primaryCategory)

The primary category that this trace event belongs to.

setTimestamp

public final void setTimestamp(long timestamp)

Timestamp in nanoseconds of the trace event.

setTrackDescriptor

public final void setTrackDescriptor(TrackDescriptor trackDescriptor)

If not null, this TraceEvent initializes a track, and the TrackDescriptor defines its properties.

setTrackUuid

public final void setTrackUuid(long trackUuid)

Set to the value of the containing Track's Track.uuid.

setType

public final void setType(int type)

Must be one of TRACE_EVENT_TYPE_UNDEFINED, TRACE_EVENT_TYPE_INSTANT, TRACE_EVENT_TYPE_BEGIN, TRACE_EVENT_TYPE_END, TRACE_EVENT_TYPE_COUNTER