Struct TrackDescriptor

pub struct TrackDescriptor {

    pub uuid: Option<u64>,
    pub parent_uuid: Option<u64>,
    pub description: Option<String>,
    pub process: Option<ProcessDescriptor>,
    pub chrome_process: Option<ChromeProcessDescriptor>,
    pub thread: Option<ThreadDescriptor>,
    pub chrome_thread: Option<ChromeThreadDescriptor>,
    pub counter: Option<CounterDescriptor>,
    pub disallow_merging_with_system_tracks: Option<bool>,
    pub child_ordering: Option<i32>,
    pub sibling_order_rank: Option<i32>,
    pub sibling_merge_behavior: Option<i32>,
    pub sibling_merge_key: Option<String>,
    pub static_or_dynamic_name: Option<StaticOrDynamicName>,
}

Defines a track for TrackEvents. Slices and instant events on the same track will be nested based on their timestamps, see TrackEvent::Type.

A TrackDescriptor only needs to be emitted by one trace writer / producer and is valid for the entirety of the trace. To ensure the descriptor isn’t lost when the ring buffer wraps, it should be reemitted whenever incremental state is cleared.

As a fallback, TrackEvents emitted without an explicit track association will be associated with an implicit trace-global track (uuid = 0), see also |TrackEvent::track_uuid|. It is possible but not necessary to emit a TrackDescriptor for this implicit track.

Next id: 17.

Fields

uuid: Option<u64>

Unique ID that identifies this track. This ID is global to the whole trace. Producers should ensure that it is unlikely to clash with IDs emitted by other producers. A value of 0 denotes the implicit trace-global track.

For example, legacy TRACE_EVENT macros may use a hash involving the async event id + id_scope, pid, and/or tid to compute this ID.

parent_uuid: Option<u64>

A parent track reference can be used to describe relationships between tracks. For example, to define an asynchronous track which is scoped to a specific process, specify the uuid for that process’s process track here. Similarly, to associate a COUNTER_THREAD_TIME_NS counter track with a thread, specify the uuid for that thread’s thread track here. In general, setting a parent will nest that track under the parent in the UI and in the trace processor data model (with the important exception noted below).

If not specified, the track will be a root track, i.e. not nested under any other track.

Note: if the thread or process fields are set, this value will be ignored as priority is given to those fields.

Note: if the parent is set to a track with thread or process fields set, the track will not be nested under the parent in the UI and in the trace processor data model. Instead, the track will inherit the parent’s thread/process association and will appear as a sibling of the parent. This semantic exists for back-compat reasons as the UI used to work this way for years and changing this leads to a lot of traces subtly breaking. If you want to force nesting, create another intermediate track to act as the parent.

description: Option<String>

A human-readable description of the track providing more context about its data. In the UI, this is shown in a popup when the track’s help button is clicked.

process: Option<ProcessDescriptor>

Associate the track with a process, making it the process-global track. There should only be one such track per process (usually for instant events; trace processor uses this fact to detect pid reuse). If you need more (e.g. for asynchronous events), create child tracks using parent_uuid.

Trace processor will merge events on a process track with slice-type events from other sources (e.g. ftrace) for the same process into a single timeline view.

chrome_process: Option<ChromeProcessDescriptor>

thread: Option<ThreadDescriptor>

Associate the track with a thread, indicating that the track’s events describe synchronous code execution on the thread. There should only be one such track per thread (trace processor uses this fact to detect tid reuse).

Trace processor will merge events on a thread track with slice-type events from other sources (e.g. ftrace) for the same thread into a single timeline view.

chrome_thread: Option<ChromeThreadDescriptor>

counter: Option<CounterDescriptor>

Descriptor for a counter track. If set, the track will only support TYPE_COUNTER TrackEvents (and values provided via TrackEvent’s |extra_counter_values|).

disallow_merging_with_system_tracks: Option<bool>

If true, forces Trace Processor to use separate tracks for track events and system events for the same thread.

Track events timestamps in Chrome have microsecond resolution, while system events use nanoseconds. It results in broken event nesting when track events and system events share a track.

child_ordering: Option<i32>

sibling_order_rank: Option<i32>

An opaque value which allows specifying how two sibling tracks should be ordered relative to each other: tracks with lower ranks will appear before tracks with higher ranks. An unspecified rank will be treated as a rank of 0.

Note: this option is only relevant for tracks where the parent has child_ordering set to EXPLICIT. It is ignored otherwise.

Note: for tracks where the parent has thread or process are set, this option is ignored (even if the parent’s child_ordering is EXPLICIT``). See parent_uuid` for details.

sibling_merge_behavior: Option<i32>

sibling_merge_key: Option<String>

An opaque value which allows specifying which tracks should be merged together.

Only meaningful when sibling_merge_behavior is set to SIBLING_MERGE_BEHAVIOR_BY_SIBLING_MERGE_KEY.

static_or_dynamic_name: Option<StaticOrDynamicName>

Name of the track.

Optional but strongly recommended to be specified in a TrackDescriptor emitted before any TrackEvents on the same track.

Note: any name specified here will be ignored for the root thread scoped tracks when disallow_merging_with_system_tracks is not set, as in this case, the name of the track is shared by many different data sources and so is centrally controlled by trace processor.

It’s strongly recommended to only emit the name for a track uuid once. If a descriptor has to be emitted multiple times (e.g. between different processes), it’s recommended to ensure that the name is consistent across all TrackDescriptors with the same uuid.

If the the above recommendation is not followed and the same uuid is emitted with different names, it is implementation defined how the final name will be chosen and may change at any time.

The current implementation of trace processor chooses the name in the following way, depending on the value of the sibling_merge_behavior field:

1. If sibling_merge_behavior is set to SIBLING_MERGE_BEHAVIOR_NONE:

   • The last non-null name in the whole trace according to trace order will be used.
   • If no non-null name is present in the whole trace, the trace processor may fall back to other sources to provide a name for the track (e.g. the first event name for slice tracks, the counter name for counter tracks). This is implementation defined and may change at any time.

2. If sibling_merge_behavior is set to any other value:

   • The first non-null name before the first event on the track or on any descendant tracks is processed will be used. For example, consider the following sequence of events: ts=100: TrackDescriptor(uuid=A) ts=200: TrackDescriptor(uuid=B, parent_uuid=A) ts=300: TrackDescriptor(uuid=A, name=“Track A”) ts=400: TrackEvent(track_uuid=B) In this case, the name for track A will be “Track A” because the descriptor with the name was emitted before the first event on a descendant track (B).
   • If no non-null name is present before the event is processed, the trace processor may fall back to other sources to provide a name for the track (e.g. the first event name for slice tracks, the counter name for counter tracks). This is implementation defined and may change at any time.
   • Note on processing order: In the standard trace processor pipeline, TrackDescriptors are processed during a “tokenization” phase, which occurs before any TrackEvents are parsed. This means that for a given track, all its descriptors in the trace are processed before its events. Consequently, the “first non-null name before the first event” will be the name from the first TrackDescriptor for that track in the trace file that has a non-null name. However, in a streaming parsing scenario, the timestamp order of descriptors and events is significant, and a descriptor arriving after an event has been processed will not be used to name the track.

Implementations

impl TrackDescriptor

pub fn uuid(&self) -> u64

Returns the value of uuid, or the default value if uuid is unset.

pub fn parent_uuid(&self) -> u64

Returns the value of parent_uuid, or the default value if parent_uuid is unset.

pub fn disallow_merging_with_system_tracks(&self) -> bool

Returns the value of disallow_merging_with_system_tracks, or the default value if disallow_merging_with_system_tracks is unset.

pub fn child_ordering(&self) -> ChildTracksOrdering

Returns the enum value of child_ordering, or the default if the field is unset or set to an invalid enum value.

pub fn set_child_ordering(&mut self, value: ChildTracksOrdering)

Sets child_ordering to the provided enum value.

pub fn sibling_order_rank(&self) -> i32

Returns the value of sibling_order_rank, or the default value if sibling_order_rank is unset.

pub fn description(&self) -> &str

Returns the value of description, or the default value if description is unset.

pub fn sibling_merge_behavior(&self) -> SiblingMergeBehavior

Returns the enum value of sibling_merge_behavior, or the default if the field is unset or set to an invalid enum value.

pub fn set_sibling_merge_behavior(&mut self, value: SiblingMergeBehavior)

Sets sibling_merge_behavior to the provided enum value.

pub fn sibling_merge_key(&self) -> &str

Returns the value of sibling_merge_key, or the default value if sibling_merge_key is unset.

Trait Implementations

impl Clone for TrackDescriptor

fn clone(&self) -> TrackDescriptor

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TrackDescriptor

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for TrackDescriptor

fn default() -> Self

Returns the “default value” for a type.

impl Message for TrackDescriptor

fn encoded_len(&self) -> usize

Returns the encoded length of the message without a length delimiter.

fn clear(&mut self)

Clears the message, resetting all fields to their default.

fn encode<B>(&self, buf: &mut B) -> Result<(), EncodeError>

where B: BufMut, Self: Sized,

Encodes the message to a buffer.

fn encode_to_vec(&self) -> Vec<u8>

where Self: Sized,

Encodes the message to a newly allocated buffer.

fn encode_length_delimited<B>(&self, buf: &mut B) -> Result<(), EncodeError>

where B: BufMut, Self: Sized,

Encodes the message with a length-delimiter to a buffer.

fn encode_length_delimited_to_vec(&self) -> Vec<u8>

where Self: Sized,

Encodes the message with a length-delimiter to a newly allocated buffer.

fn decode<B>(buf: B) -> Result<Self, DecodeError>

where B: Buf, Self: Default,

Decodes an instance of the message from a buffer.

fn decode_length_delimited<B>(buf: B) -> Result<Self, DecodeError>

where B: Buf, Self: Default,

Decodes a length-delimited instance of the message from the buffer.

fn merge<B>(&mut self, buf: B) -> Result<(), DecodeError>

where B: Buf, Self: Sized,

Decodes an instance of the message from a buffer, and merges it into self.

fn merge_length_delimited<B>(&mut self, buf: B) -> Result<(), DecodeError>

where B: Buf, Self: Sized,

Decodes a length-delimited instance of the message from buffer, and merges it into self.

impl PartialEq for TrackDescriptor

fn eq(&self, other: &TrackDescriptor) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for TrackDescriptor