package cactus_tracing.vendor.perfetto.protos

Get desktop application:
View/edit binary Protocol Buffers messages

Defines properties of a counter track, e.g. for built-in counters (thread time, instruction count, ..) or user-specified counters (e.g. memory usage of a specific app component). Counter tracks only support TYPE_COUNTER track events, which specify new values for the counter. For counters that require per-slice values, counter values can instead be provided in a more efficient encoding via TrackEvent's |extra_counter_track_uuids| and |extra_counter_values| fields. However, slice-type events cannot be emitted onto a counter track. Values for counters that are only emitted on a single packet sequence can optionally be delta-encoded, see |is_incremental|. Next id: 7.

Used in: TrackDescriptor

• optional CounterDescriptor.BuiltinCounterType type = 1

  For built-in counters (e.g. thread time). Custom user-specified counters (e.g. those emitted by TRACE_COUNTER macros of the client library) shouldn't set this, and instead provide a counter name via TrackDescriptor.

• repeated string categories = 2

  Names of categories of the counter (usually for user-specified counters). In the client library, categories are a way to turn groups of individual counters (or events) on or off.

• optional CounterDescriptor.Unit unit = 3

  Type of the counter's values. Built-in counters imply a value for this field.

• optional string unit_name = 6

  In order to use a unit not defined as a part of |Unit|, a free-form unit name can be used instead.

• optional int64 unit_multiplier = 4

  Multiplication factor of this counter's values, e.g. to supply COUNTER_THREAD_TIME_NS timestamps in microseconds instead.

• optional bool is_incremental = 5

  Whether values for this counter are provided as delta values. Only supported for counters that are emitted on a single packet-sequence (e.g. thread time). Counter values in subsequent packets on the current packet sequence will be interpreted as delta values from the sequence's most recent value for the counter. When incremental state is cleared, the counter value is considered to be reset to 0. Thus, the first value after incremental state is cleared is effectively an absolute value.

Built-in counters, usually with special meaning in the client library, trace processor, legacy JSON format, or UI. Trace processor will infer a track name from the enum value if none is provided in TrackDescriptor.

Used in: CounterDescriptor

• COUNTER_UNSPECIFIED = 0

• COUNTER_THREAD_TIME_NS = 1

  implies UNIT_TIME_NS.

• COUNTER_THREAD_INSTRUCTION_COUNT = 2

  implies UNIT_COUNT.

Type of the values for the counters - to supply lower granularity units, see also |unit_multiplier|.

Used in: CounterDescriptor

• UNIT_UNSPECIFIED = 0

• UNIT_TIME_NS = 1

• UNIT_COUNT = 2

• UNIT_SIZE_BYTES = 3

  TODO(eseckler): Support more units as necessary.

Used in: InternedData

• optional uint64 iid = 1

• optional string name = 2

Used in: InternedData

• optional uint64 iid = 1

• optional string name = 2

Message that contains new entries for the interning indices of a packet sequence. The writer will usually emit new entries in the same TracePacket that first refers to them (since the last reset of interning state). They may also be emitted proactively in advance of referring to them in later packets. Next reserved id: 8 (up to 15). Next id: 36.

TODO(eseckler): Replace iid fields inside interned messages with map<iid, message> type fields in InternedData.

Used in: TracePacket

• repeated EventCategory event_categories = 1

  Each field's message type needs to specify an |iid| field, which is the ID of the entry in the field's interning index. Each field constructs its own index, thus interning IDs are scoped to the tracing session and field (usually as a counter for efficient var-int encoding), and optionally to the incremental state generation of the packet sequence.

• repeated EventName event_names = 2

• repeated SourceLocation source_locations = 4

Describes a process's attributes. Emitted as part of a TrackDescriptor, usually by the process's main thread. Next id: 9.

Used in: TrackDescriptor

• optional int32 pid = 1

• repeated string cmdline = 2

• optional string process_name = 6

• optional int32 process_priority = 5

• optional int64 start_timestamp_ns = 7

  Process start time in nanoseconds. The timestamp refers to the trace clock by default. Other clock IDs provided in TracePacket are not supported.

Used in: InternedData, TrackEvent

• optional uint64 iid = 1

• optional string file_name = 2

• optional string function_name = 3

• optional uint32 line_number = 4

Describes a thread's attributes. Emitted as part of a TrackDescriptor, usually by the thread's trace writer. Next id: 9.

Used in: TrackDescriptor

• optional int32 pid = 1

• optional int32 tid = 2

• optional string thread_name = 5

• repeated TracePacket packet = 1

TracePacket is the root object of a Perfetto trace. A Perfetto trace is a linear sequence of TracePacket(s). The tracing service guarantees that all TracePacket(s) written by a given TraceWriter are seen in-order, without gaps or duplicates. If, for any reason, a TraceWriter sequence becomes invalid, no more packets are returned to the Consumer (or written into the trace file). TracePacket(s) written by different TraceWriter(s), hence even different data sources, can be seen in arbitrary order. The consumer can re-establish a total order, if interested, using the packet timestamps, after having synchronized the different clocks onto a global clock. The tracing service is agnostic of the content of TracePacket, with the exception of few fields (e.g.. trusted_*, trace_config) that are written by the service itself. See the [Buffers and Dataflow](/docs/concepts/buffers.md) doc for details. Next reserved id: 14 (up to 15). Next id: 95.

Used in: Trace

• optional uint64 timestamp = 8

  The timestamp of the TracePacket. By default this timestamps refers to the trace clock (CLOCK_BOOTTIME on Android). It can be overridden using a different timestamp_clock_id. The clock domain definition in ClockSnapshot can also override: - The unit (default: 1ns). - The absolute vs delta encoding (default: absolute timestamp). INCLUSION REASON: event timestamp

• optional uint32 timestamp_clock_id = 58

  Specifies the ID of the clock used for the TracePacket |timestamp|. Can be one of the built-in types from ClockSnapshot::BuiltinClocks, or a producer-defined clock id. If unspecified and if no default per-sequence value has been provided via TracePacketDefaults, it defaults to BuiltinClocks::BOOTTIME. INCLUSION REASON: event timestamp

• oneof data

  INCLUSION REASON: trace data

  • TrackEvent track_event = 11

    INCLUSION REASON: track event is the span information

  • TrackDescriptor track_descriptor = 60

    Only used by TrackEvent. INCLUSION REASON: this describes the track

  • bytes synchronization_marker = 36

    This field is emitted at periodic intervals (~10s) and contains always the binary representation of the UUID {82477a76-b28d-42ba-81dc-33326d57a079}. This is used to be able to efficiently partition long traces without having to fully parse them. TODO: uncertain if this is needed.

• oneof optional_trusted_packet_sequence_id

  Service-assigned identifier of the packet sequence this packet belongs to. Uniquely identifies a producer + writer pair within the tracing session. A value of zero denotes an invalid ID. Keep in sync with TrustedPacket.trusted_packet_sequence_id. INCLUSION REASON: required field for the sequences

  • uint32 trusted_packet_sequence_id = 10

• optional InternedData interned_data = 12

  Incrementally emitted interned data, valid only on the packet's sequence (packets with the same |trusted_packet_sequence_id|). The writer will usually emit new interned data in the same TracePacket that first refers to it (since the last reset of interning state). It may also be emitted proactively in advance of referring to them in later packets. INCLUSION REASON: for interning string and other data.

• optional uint32 sequence_flags = 13

  INCLUSION REASON: This is required for interned data. Also the flags are supposed to be binary OR'ed

• optional bool previous_packet_dropped = 42

  Flag set by the service if, for the current packet sequence (see |trusted_packet_sequence_id|), either: * this is the first packet, or * one or multiple packets were dropped since the last packet that the consumer read from the sequence. This can happen if chunks in the trace buffer are overridden before the consumer could read them when the trace is configured in ring buffer mode. When packet loss occurs, incrementally emitted data (including interned data) on the sequence should be considered invalid up until the next packet with SEQ_INCREMENTAL_STATE_CLEARED set.

• optional bool first_packet_on_sequence = 87

  Flag set by a producer (starting from SDK v29) if, for the current packet sequence (see |trusted_packet_sequence_id|), this is the first packet. This flag can be used for distinguishing the two situations when processing the trace: 1. There are no prior events for the sequence because of data loss, e.g. due to ring buffer wrapping. 2. There are no prior events for the sequence because it didn't start before this packet (= there's definitely no preceding data loss). Given that older SDK versions do not support this flag, this flag not being present for a particular sequence does not necessarily imply data loss.

• SEQ_UNSPECIFIED = 0

• SEQ_INCREMENTAL_STATE_CLEARED = 1

  Set by the writer to indicate that it will re-emit any incremental data for the packet's sequence before referring to it again. This includes interned data as well as periodically emitted data like Process/ThreadDescriptors. This flag only affects the current packet sequence (see |trusted_packet_sequence_id|). When set, this TracePacket and subsequent TracePackets on the same sequence will not refer to any incremental data emitted before this TracePacket. For example, previously emitted interned data will be re-emitted if it is referred to again. When the reader detects packet loss (|previous_packet_dropped|), it needs to skip packets in the sequence until the next one with this flag set, to ensure intact incremental data.

• SEQ_NEEDS_INCREMENTAL_STATE = 2

  This packet requires incremental state, such as TracePacketDefaults or InternedData, to be parsed correctly. The trace reader should skip this packet if incremental state is not valid on this sequence, i.e. if no packet with the SEQ_INCREMENTAL_STATE_CLEARED flag has been seen on the current |trusted_packet_sequence_id|.

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: 10.

Used in: TracePacket

• optional uint64 uuid = 1

  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.

• optional uint64 parent_uuid = 5

  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.

• optional string name = 2

  Name of the track. Optional - if unspecified, it may be derived from the process/thread name (process/thread tracks), the first event's name (async tracks), or counter name (counter tracks).

• optional ProcessDescriptor process = 3

  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.

• optional ThreadDescriptor thread = 4

  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.

• optional CounterDescriptor counter = 8

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

• optional bool disallow_merging_with_system_tracks = 9

  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.

Trace events emitted by client instrumentation library (TRACE_EVENT macros), which describe activity on a track, such as a thread or asynchronous event track. The track is specified using separate TrackDescriptor messages and referred to via the track's UUID. A simple TrackEvent packet specifies a timestamp, category, name and type: ```protobuf trace_packet { timestamp: 1000 track_event { categories: ["my_cat"] name: "my_event" type: TYPE_INSTANT } } ``` To associate an event with a custom track (e.g. a thread), the track is defined in a separate packet and referred to from the TrackEvent by its UUID: ```protobuf trace_packet { track_descriptor { track_uuid: 1234 name: "my_track" // Optionally, associate the track with a thread. thread_descriptor { pid: 10 tid: 10 .. } } } ``` A pair of TYPE_SLICE_BEGIN and _END events form a slice on the track: ```protobuf trace_packet { timestamp: 1200 track_event { track_uuid: 1234 categories: ["my_cat"] name: "my_slice" type: TYPE_SLICE_BEGIN } } trace_packet { timestamp: 1400 track_event { track_uuid: 1234 type: TYPE_SLICE_END } } ``` TrackEvents also support optimizations to reduce data repetition and encoded data size, e.g. through data interning (names, categories, ...) and delta encoding of timestamps/counters. For details, see the InternedData message. Further, default values for attributes of events on the same sequence (e.g. their default track association) can be emitted as part of a TrackEventDefaults message. Next reserved id: 13 (up to 15). Next id: 51.

Used in: TracePacket

• repeated uint64 category_iids = 3

  Names of categories of the event. In the client library, categories are a way to turn groups of individual events on or off. interned EventCategoryName.

• repeated string categories = 22

  non-interned variant.

• oneof name_field

  Optional name of the event for its display in trace viewer. May be left unspecified for events with typed arguments. Note that metrics should not rely on event names, as they are prone to changing. Instead, they should use typed arguments to identify the events they are interested in.

  • uint64 name_iid = 10

    interned EventName.

  • string name = 23

    non-interned variant.

• optional TrackEvent.Type type = 9

• optional uint64 track_uuid = 11

  Identifies the track of the event. The default value may be overridden using TrackEventDefaults, e.g., to specify the track of the TraceWriter's sequence (in most cases sequence = one thread). If no value is specified here or in TrackEventDefaults, the TrackEvent will be associated with an implicit trace-global track (uuid 0). See TrackDescriptor::uuid.

• oneof counter_value_field

  A new value for a counter track. |track_uuid| should refer to a track with a CounterDescriptor, and |type| should be TYPE_COUNTER. For a more efficient encoding of counter values that are sampled at the beginning/end of a slice, see |extra_counter_values| and |extra_counter_track_uuids|. Counter values can optionally be encoded in as delta values (positive or negative) on each packet sequence (see CounterIncrementalBase).

  • int64 counter_value = 30

  • double double_counter_value = 44

• repeated uint64 extra_counter_track_uuids = 31

  To encode counter values more efficiently, we support attaching additional counter values to a TrackEvent of any type. All values will share the same timestamp specified in the TracePacket. The value at extra_counter_values[N] is for the counter track referenced by extra_counter_track_uuids[N]. |extra_counter_track_uuids| may also be set via TrackEventDefaults. There should always be equal or more uuids than values. It is valid to set more uuids (e.g. via defaults) than values. If uuids are specified in TrackEventDefaults and a TrackEvent, the TrackEvent uuids override the default uuid list. For example, this allows snapshotting the thread time clock at each thread-track BEGIN and END event to capture the cpu time delta of a slice.

• repeated int64 extra_counter_values = 12

• repeated uint64 extra_double_counter_track_uuids = 45

  Counter snapshots using floating point instead of integer values.

• repeated double extra_double_counter_values = 46

• repeated fixed64 flow_ids = 47

  IDs of flows originating, passing through, or ending at this event. Flow IDs are global within a trace. A flow connects a sequence of TrackEvents within or across tracks, e.g. an input event may be handled on one thread but cause another event on a different thread - a flow between the two events can associate them. The direction of the flows between events is inferred from the events' timestamps. The earliest event with the same flow ID becomes the source of the flow. Any events thereafter are intermediate steps of the flow, until the flow terminates at the last event with the flow ID. Flows can also be explicitly terminated (see |terminating_flow_ids|), so that the same ID can later be reused for another flow.

• repeated fixed64 terminating_flow_ids = 48

  List of flow ids which should terminate on this event, otherwise same as |flow_ids|. Any one flow ID should be either listed as part of |flow_ids| OR |terminating_flow_ids|, not both.

• oneof source_location_field

  This field is used only if the source location represents the function that executes during this event.

  • SourceLocation source_location = 33

    Non-interned field.

  • uint64 source_location_iid = 34

    Interned field.

Type of the TrackEvent (required if |phase| in LegacyEvent is not set).

Used in: TrackEvent

• TYPE_UNSPECIFIED = 0

• TYPE_SLICE_BEGIN = 1

  Slice events are events that have a begin and end timestamp, i.e. a duration. They can be nested similar to a callstack: If, on the same track, event B begins after event A, but before A ends, B is a child event of A and will be drawn as a nested event underneath A in the UI. Note that child events should always end before their parents (e.g. B before A). Each slice event is formed by a pair of BEGIN + END events. The END event does not need to repeat any TrackEvent fields it has in common with its corresponding BEGIN event. Arguments and debug annotations of the BEGIN + END pair will be merged during trace import. Note that we deliberately chose not to support COMPLETE events (which would specify a duration directly) since clients would need to delay writing them until the slice is completed, which can result in reordered events in the trace and loss of unfinished events at the end of a trace.

• TYPE_SLICE_END = 2

• TYPE_INSTANT = 3

  Instant events are nestable events without duration. They can be children of slice events on the same track.

• TYPE_COUNTER = 4

  Event that provides a value for a counter track. |track_uuid| should refer to a counter track and |counter_value| set to the new value. Note that most other TrackEvent fields (e.g. categories, name, ..) are not supported for TYPE_COUNTER events. See also CounterDescriptor.

A source location, represented as a native symbol. This is similar to `message Frame` from protos/perfetto/trace/profiling/profile_common.proto, but for abitrary source code locations (for example in track event args), not stack frames.

• optional uint64 iid = 1

• optional uint64 mapping_id = 2

• optional uint64 rel_pc = 3