1/* 2 * Copyright (C) 2017 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17syntax = "proto2"; 18 19import "protos/perfetto/common/trace_stats.proto"; 20import "protos/perfetto/config/trace_config.proto"; 21import "protos/perfetto/trace/extension_descriptor.proto"; 22import "protos/perfetto/trace/android/android_game_intervention_list.proto"; 23import "protos/perfetto/trace/android/android_log.proto"; 24import "protos/perfetto/trace/android/android_system_property.proto"; 25import "protos/perfetto/trace/android/camera_event.proto"; 26import "protos/perfetto/trace/android/frame_timeline_event.proto"; 27import "protos/perfetto/trace/android/gpu_mem_event.proto"; 28import "protos/perfetto/trace/android/graphics_frame_event.proto"; 29import "protos/perfetto/trace/android/initial_display_state.proto"; 30import "protos/perfetto/trace/android/network_trace.proto"; 31import "protos/perfetto/trace/android/packages_list.proto"; 32import "protos/perfetto/trace/chrome/chrome_benchmark_metadata.proto"; 33import "protos/perfetto/trace/chrome/chrome_metadata.proto"; 34import "protos/perfetto/trace/chrome/chrome_trace_event.proto"; 35import "protos/perfetto/trace/clock_snapshot.proto"; 36import "protos/perfetto/trace/filesystem/inode_file_map.proto"; 37import "protos/perfetto/trace/ftrace/ftrace_event_bundle.proto"; 38import "protos/perfetto/trace/ftrace/ftrace_stats.proto"; 39import "protos/perfetto/trace/gpu/gpu_counter_event.proto"; 40import "protos/perfetto/trace/gpu/gpu_log.proto"; 41import "protos/perfetto/trace/gpu/gpu_render_stage_event.proto"; 42import "protos/perfetto/trace/gpu/vulkan_memory_event.proto"; 43import "protos/perfetto/trace/gpu/vulkan_api_event.proto"; 44import "protos/perfetto/trace/interned_data/interned_data.proto"; 45import "protos/perfetto/trace/memory_graph.proto"; 46import "protos/perfetto/trace/perfetto/perfetto_metatrace.proto"; 47import "protos/perfetto/trace/perfetto/tracing_service_event.proto"; 48import "protos/perfetto/trace/power/android_energy_estimation_breakdown.proto"; 49import "protos/perfetto/trace/power/android_entity_state_residency.proto"; 50import "protos/perfetto/trace/power/battery_counters.proto"; 51import "protos/perfetto/trace/power/power_rails.proto"; 52import "protos/perfetto/trace/statsd/statsd_atom.proto"; 53import "protos/perfetto/trace/profiling/deobfuscation.proto"; 54import "protos/perfetto/trace/profiling/heap_graph.proto"; 55import "protos/perfetto/trace/profiling/profile_common.proto"; 56import "protos/perfetto/trace/profiling/profile_packet.proto"; 57import "protos/perfetto/trace/profiling/smaps.proto"; 58import "protos/perfetto/trace/ps/process_stats.proto"; 59import "protos/perfetto/trace/ps/process_tree.proto"; 60import "protos/perfetto/trace/sys_stats/sys_stats.proto"; 61import "protos/perfetto/trace/system_info.proto"; 62import "protos/perfetto/trace/system_info/cpu_info.proto"; 63import "protos/perfetto/trace/trace_packet_defaults.proto"; 64import "protos/perfetto/trace/track_event/process_descriptor.proto"; 65import "protos/perfetto/trace/track_event/range_of_interest.proto"; 66import "protos/perfetto/trace/track_event/thread_descriptor.proto"; 67import "protos/perfetto/trace/track_event/track_descriptor.proto"; 68import "protos/perfetto/trace/track_event/track_event.proto"; 69import "protos/perfetto/trace/translation/translation_table.proto"; 70import "protos/perfetto/trace/trace_uuid.proto"; 71import "protos/perfetto/trace/trigger.proto"; 72import "protos/perfetto/trace/test_event.proto"; 73import "protos/perfetto/trace/ui_state.proto"; 74 75package perfetto.protos; 76 77// TracePacket is the root object of a Perfetto trace. 78// A Perfetto trace is a linear sequence of TracePacket(s). 79// 80// The tracing service guarantees that all TracePacket(s) written by a given 81// TraceWriter are seen in-order, without gaps or duplicates. If, for any 82// reason, a TraceWriter sequence becomes invalid, no more packets are returned 83// to the Consumer (or written into the trace file). 84// TracePacket(s) written by different TraceWriter(s), hence even different 85// data sources, can be seen in arbitrary order. 86// The consumer can re-establish a total order, if interested, using the packet 87// timestamps, after having synchronized the different clocks onto a global 88// clock. 89// 90// The tracing service is agnostic of the content of TracePacket, with the 91// exception of few fields (e.g.. trusted_*, trace_config) that are written by 92// the service itself. 93// 94// See the [Buffers and Dataflow](/docs/concepts/buffers.md) doc for details. 95// 96// Next reserved id: 14 (up to 15). 97// Next id: 93. 98message TracePacket { 99 // The timestamp of the TracePacket. 100 // By default this timestamps refers to the trace clock (CLOCK_BOOTTIME on 101 // Android). It can be overridden using a different timestamp_clock_id. 102 // The clock domain definition in ClockSnapshot can also override: 103 // - The unit (default: 1ns). 104 // - The absolute vs delta encoding (default: absolute timestamp). 105 optional uint64 timestamp = 8; 106 107 // Specifies the ID of the clock used for the TracePacket |timestamp|. Can be 108 // one of the built-in types from ClockSnapshot::BuiltinClocks, or a 109 // producer-defined clock id. 110 // If unspecified and if no default per-sequence value has been provided via 111 // TracePacketDefaults, it defaults to BuiltinClocks::BOOTTIME. 112 optional uint32 timestamp_clock_id = 58; 113 114 oneof data { 115 ProcessTree process_tree = 2; 116 ProcessStats process_stats = 9; 117 InodeFileMap inode_file_map = 4; 118 ChromeEventBundle chrome_events = 5; 119 ClockSnapshot clock_snapshot = 6; 120 SysStats sys_stats = 7; 121 TrackEvent track_event = 11; 122 123 // IDs up to 15 are reserved. They take only one byte to encode their 124 // preamble so should be used for frequent events. 125 126 TraceUuid trace_uuid = 89; 127 TraceConfig trace_config = 33; 128 FtraceStats ftrace_stats = 34; 129 TraceStats trace_stats = 35; 130 ProfilePacket profile_packet = 37; 131 StreamingAllocation streaming_allocation = 74; 132 StreamingFree streaming_free = 75; 133 BatteryCounters battery = 38; 134 PowerRails power_rails = 40; 135 AndroidLogPacket android_log = 39; 136 SystemInfo system_info = 45; 137 Trigger trigger = 46; 138 PackagesList packages_list = 47; 139 ChromeBenchmarkMetadata chrome_benchmark_metadata = 48; 140 PerfettoMetatrace perfetto_metatrace = 49; 141 ChromeMetadataPacket chrome_metadata = 51; 142 GpuCounterEvent gpu_counter_event = 52; 143 GpuRenderStageEvent gpu_render_stage_event = 53; 144 StreamingProfilePacket streaming_profile_packet = 54; 145 HeapGraph heap_graph = 56; 146 GraphicsFrameEvent graphics_frame_event = 57; 147 VulkanMemoryEvent vulkan_memory_event = 62; 148 GpuLog gpu_log = 63; 149 VulkanApiEvent vulkan_api_event = 65; 150 PerfSample perf_sample = 66; 151 CpuInfo cpu_info = 67; 152 SmapsPacket smaps_packet = 68; 153 TracingServiceEvent service_event = 69; 154 InitialDisplayState initial_display_state = 70; 155 GpuMemTotalEvent gpu_mem_total_event = 71; 156 MemoryTrackerSnapshot memory_tracker_snapshot = 73; 157 FrameTimelineEvent frame_timeline_event = 76; 158 AndroidEnergyEstimationBreakdown android_energy_estimation_breakdown = 77; 159 UiState ui_state = 78; 160 AndroidCameraFrameEvent android_camera_frame_event = 80; 161 AndroidCameraSessionStats android_camera_session_stats = 81; 162 TranslationTable translation_table = 82; 163 AndroidGameInterventionList android_game_intervention_list = 83; 164 StatsdAtom statsd_atom = 84; 165 AndroidSystemProperty android_system_property = 86; 166 EntityStateResidency entity_state_residency = 91; 167 168 // Only used in profile packets. 169 ProfiledFrameSymbols profiled_frame_symbols = 55; 170 ModuleSymbols module_symbols = 61; 171 DeobfuscationMapping deobfuscation_mapping = 64; 172 173 // Only used by TrackEvent. 174 TrackDescriptor track_descriptor = 60; 175 176 // Deprecated, use TrackDescriptor instead. 177 ProcessDescriptor process_descriptor = 43; 178 179 // Deprecated, use TrackDescriptor instead. 180 ThreadDescriptor thread_descriptor = 44; 181 182 // Events from the Linux kernel ftrace infrastructure. 183 FtraceEventBundle ftrace_events = 1; 184 185 // This field is emitted at periodic intervals (~10s) and 186 // contains always the binary representation of the UUID 187 // {82477a76-b28d-42ba-81dc-33326d57a079}. This is used to be able to 188 // efficiently partition long traces without having to fully parse them. 189 bytes synchronization_marker = 36; 190 191 // Zero or more proto encoded trace packets compressed using deflate. 192 // Each compressed_packets TracePacket (including the two field ids and 193 // sizes) should be less than 512KB. 194 bytes compressed_packets = 50; 195 196 // Data sources can extend the trace proto with custom extension protos (see 197 // docs/design-docs/extensions.md). When they do that, the descriptor of 198 // their extension proto descriptor is serialized in this packet. This 199 // allows trace_processor to deserialize extended messages using reflection 200 // even if the extension proto is not checked in the Perfetto repo. 201 ExtensionDescriptor extension_descriptor = 72; 202 203 // Represents a single packet sent or received by the network. 204 NetworkPacketEvent network_packet = 88; 205 206 // Represents one or more packets sent or received by the network. 207 NetworkPacketBundle network_packet_bundle = 92; 208 209 // The "range of interest" for track events. See the message definition 210 // comments for more details. 211 TrackEventRangeOfInterest track_event_range_of_interest = 90; 212 213 // This field is only used for testing. 214 // In previous versions of this proto this field had the id 268435455 215 // This caused many problems: 216 // - protozero decoder does not handle field ids larger than 999. 217 // - old versions of protoc produce Java bindings with syntax errors when 218 // the field id is large enough. 219 TestEvent for_testing = 900; 220 } 221 222 // Trusted user id of the producer which generated this packet. Keep in sync 223 // with TrustedPacket.trusted_uid. 224 // 225 // TODO(eseckler): Emit this field in a PacketSequenceDescriptor message 226 // instead. 227 oneof optional_trusted_uid { int32 trusted_uid = 3; }; 228 229 // Service-assigned identifier of the packet sequence this packet belongs to. 230 // Uniquely identifies a producer + writer pair within the tracing session. A 231 // value of zero denotes an invalid ID. Keep in sync with 232 // TrustedPacket.trusted_packet_sequence_id. 233 oneof optional_trusted_packet_sequence_id { 234 uint32 trusted_packet_sequence_id = 10; 235 } 236 237 // Trusted process id of the producer which generated this packet, written by 238 // the service. 239 optional int32 trusted_pid = 79; 240 241 // Incrementally emitted interned data, valid only on the packet's sequence 242 // (packets with the same |trusted_packet_sequence_id|). The writer will 243 // usually emit new interned data in the same TracePacket that first refers to 244 // it (since the last reset of interning state). It may also be emitted 245 // proactively in advance of referring to them in later packets. 246 optional InternedData interned_data = 12; 247 248 enum SequenceFlags { 249 SEQ_UNSPECIFIED = 0; 250 251 // Set by the writer to indicate that it will re-emit any incremental data 252 // for the packet's sequence before referring to it again. This includes 253 // interned data as well as periodically emitted data like 254 // Process/ThreadDescriptors. This flag only affects the current packet 255 // sequence (see |trusted_packet_sequence_id|). 256 // 257 // When set, this TracePacket and subsequent TracePackets on the same 258 // sequence will not refer to any incremental data emitted before this 259 // TracePacket. For example, previously emitted interned data will be 260 // re-emitted if it is referred to again. 261 // 262 // When the reader detects packet loss (|previous_packet_dropped|), it needs 263 // to skip packets in the sequence until the next one with this flag set, to 264 // ensure intact incremental data. 265 SEQ_INCREMENTAL_STATE_CLEARED = 1; 266 267 // This packet requires incremental state, such as TracePacketDefaults or 268 // InternedData, to be parsed correctly. The trace reader should skip this 269 // packet if incremental state is not valid on this sequence, i.e. if no 270 // packet with the SEQ_INCREMENTAL_STATE_CLEARED flag has been seen on the 271 // current |trusted_packet_sequence_id|. 272 SEQ_NEEDS_INCREMENTAL_STATE = 2; 273 }; 274 optional uint32 sequence_flags = 13; 275 276 // DEPRECATED. Moved to SequenceFlags::SEQ_INCREMENTAL_STATE_CLEARED. 277 optional bool incremental_state_cleared = 41; 278 279 // Default values for fields of later TracePackets emitted on this packet's 280 // sequence (TracePackets with the same |trusted_packet_sequence_id|). 281 // It must be reemitted when incremental state is cleared (see 282 // |incremental_state_cleared|). 283 // Requires that any future packet emitted on the same sequence specifies 284 // the SEQ_NEEDS_INCREMENTAL_STATE flag. 285 // TracePacketDefaults always override the global defaults for any future 286 // packet on this sequence (regardless of SEQ_NEEDS_INCREMENTAL_STATE). 287 optional TracePacketDefaults trace_packet_defaults = 59; 288 289 // Flag set by the service if, for the current packet sequence (see 290 // |trusted_packet_sequence_id|), either: 291 // * this is the first packet, or 292 // * one or multiple packets were dropped since the last packet that the 293 // consumer read from the sequence. This can happen if chunks in the trace 294 // buffer are overridden before the consumer could read them when the trace 295 // is configured in ring buffer mode. 296 // 297 // When packet loss occurs, incrementally emitted data (including interned 298 // data) on the sequence should be considered invalid up until the next packet 299 // with SEQ_INCREMENTAL_STATE_CLEARED set. 300 optional bool previous_packet_dropped = 42; 301 302 // Flag set by a producer (starting from SDK v29) if, for the current packet 303 // sequence (see |trusted_packet_sequence_id|), this is the first packet. 304 // 305 // This flag can be used for distinguishing the two situations when 306 // processing the trace: 307 // 1. There are no prior events for the sequence because of data loss, e.g. 308 // due to ring buffer wrapping. 309 // 2. There are no prior events for the sequence because it didn't start 310 // before this packet (= there's definitely no preceeding data loss). 311 // 312 // Given that older SDK versions do not support this flag, this flag not 313 // being present for a particular sequence does not necessarily imply data 314 // loss. 315 optional bool first_packet_on_sequence = 87; 316} 317