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