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