1perf.data format 2 3Uptodate as of v4.7 4 5This document describes the on-disk perf.data format, generated by perf record 6or perf inject and consumed by the other perf tools. 7 8On a high level perf.data contains the events generated by the PMUs, plus metadata. 9 10All fields are in native-endian of the machine that generated the perf.data. 11 12When perf is writing to a pipe it uses a special version of the file 13format that does not rely on seeking to adjust data offsets. This 14format is described in "Pipe-mode data" section. The pipe data version can be 15augmented with additional events using perf inject. 16 17The file starts with a perf_header: 18 19struct perf_header { 20 char magic[8]; /* PERFILE2 */ 21 uint64_t size; /* size of the header */ 22 uint64_t attr_size; /* size of an attribute in attrs */ 23 struct perf_file_section attrs; 24 struct perf_file_section data; 25 struct perf_file_section event_types; 26 uint64_t flags; 27 uint64_t flags1[3]; 28}; 29 30The magic number identifies the perf file and the version. Current perf versions 31use PERFILE2. Old perf versions generated a version 1 format (PERFFILE). Version 1 32is not described here. The magic number also identifies the endian. When the 33magic value is 64bit byte swapped compared the file is in non-native 34endian. 35 36A perf_file_section contains a pointer to another section of the perf file. 37The header contains three such pointers: for attributes, data and event types. 38 39struct perf_file_section { 40 uint64_t offset; /* offset from start of file */ 41 uint64_t size; /* size of the section */ 42}; 43 44Flags section: 45 46The header is followed by different optional headers, described by the bits set 47in flags. Only headers for which the bit is set are included. Each header 48consists of a perf_file_section located after the initial header. 49The respective perf_file_section points to the data of the additional 50header and defines its size. 51 52Some headers consist of strings, which are defined like this: 53 54struct perf_header_string { 55 uint32_t len; 56 char string[len]; /* zero terminated */ 57}; 58 59Some headers consist of a sequence of strings, which start with a 60 61struct perf_header_string_list { 62 uint32_t nr; 63 struct perf_header_string strings[nr]; /* variable length records */ 64}; 65 66The bits are the flags bits in a 256 bit bitmap starting with 67flags. These define the valid bits: 68 69 HEADER_RESERVED = 0, /* always cleared */ 70 HEADER_FIRST_FEATURE = 1, 71 HEADER_TRACING_DATA = 1, 72 73Describe me. 74 75 HEADER_BUILD_ID = 2, 76 77The header consists of an sequence of build_id_event. The size of each record 78is defined by header.size (see perf_event.h). Each event defines a ELF build id 79for a executable file name for a pid. An ELF build id is a unique identifier 80assigned by the linker to an executable. 81 82struct build_id_event { 83 struct perf_event_header header; 84 pid_t pid; 85 uint8_t build_id[24]; 86 char filename[header.size - offsetof(struct build_id_event, filename)]; 87}; 88 89 HEADER_HOSTNAME = 3, 90 91A perf_header_string with the hostname where the data was collected 92(uname -n) 93 94 HEADER_OSRELEASE = 4, 95 96A perf_header_string with the os release where the data was collected 97(uname -r) 98 99 HEADER_VERSION = 5, 100 101A perf_header_string with the perf user tool version where the 102data was collected. This is the same as the version of the source tree 103the perf tool was built from. 104 105 HEADER_ARCH = 6, 106 107A perf_header_string with the CPU architecture (uname -m) 108 109 HEADER_NRCPUS = 7, 110 111A structure defining the number of CPUs. 112 113struct nr_cpus { 114 uint32_t nr_cpus_online; 115 uint32_t nr_cpus_available; /* CPUs not yet onlined */ 116}; 117 118 HEADER_CPUDESC = 8, 119 120A perf_header_string with description of the CPU. On x86 this is the model name 121in /proc/cpuinfo 122 123 HEADER_CPUID = 9, 124 125A perf_header_string with the exact CPU type. On x86 this is 126vendor,family,model,stepping. For example: GenuineIntel,6,69,1 127 128 HEADER_TOTAL_MEM = 10, 129 130An uint64_t with the total memory in bytes. 131 132 HEADER_CMDLINE = 11, 133 134A perf_header_string with the perf command line used to collect the data. 135 136 HEADER_EVENT_DESC = 12, 137 138Another description of the perf_event_attrs, more detailed than header.attrs 139including IDs and names. See perf_event.h or the man page for a description 140of a struct perf_event_attr. 141 142struct { 143 uint32_t nr; /* number of events */ 144 uint32_t attr_size; /* size of each perf_event_attr */ 145 struct { 146 struct perf_event_attr attr; /* size of attr_size */ 147 uint32_t nr_ids; 148 struct perf_header_string event_string; 149 uint64_t ids[nr_ids]; 150 } events[nr]; /* Variable length records */ 151}; 152 153 HEADER_CPU_TOPOLOGY = 13, 154 155String lists defining the core and CPU threads topology. 156 157struct { 158 struct perf_header_string_list cores; /* Variable length */ 159 struct perf_header_string_list threads; /* Variable length */ 160}; 161 162Example: 163 sibling cores : 0-3 164 sibling threads : 0-1 165 sibling threads : 2-3 166 167 HEADER_NUMA_TOPOLOGY = 14, 168 169 A list of NUMA node descriptions 170 171struct { 172 uint32_t nr; 173 struct { 174 uint32_t nodenr; 175 uint64_t mem_total; 176 uint64_t mem_free; 177 struct perf_header_string cpus; 178 } nodes[nr]; /* Variable length records */ 179}; 180 181 HEADER_BRANCH_STACK = 15, 182 183Not implemented in perf. 184 185 HEADER_PMU_MAPPINGS = 16, 186 187 A list of PMU structures, defining the different PMUs supported by perf. 188 189struct { 190 uint32_t nr; 191 struct pmu { 192 uint32_t pmu_type; 193 struct perf_header_string pmu_name; 194 } [nr]; /* Variable length records */ 195}; 196 197 HEADER_GROUP_DESC = 17, 198 199 Description of counter groups ({...} in perf syntax) 200 201struct { 202 uint32_t nr; 203 struct { 204 struct perf_header_string string; 205 uint32_t leader_idx; 206 uint32_t nr_members; 207 } [nr]; /* Variable length records */ 208}; 209 210 HEADER_AUXTRACE = 18, 211 212Define additional auxtrace areas in the perf.data. auxtrace is used to store 213undecoded hardware tracing information, such as Intel Processor Trace data. 214 215/** 216 * struct auxtrace_index_entry - indexes a AUX area tracing event within a 217 * perf.data file. 218 * @file_offset: offset within the perf.data file 219 * @sz: size of the event 220 */ 221struct auxtrace_index_entry { 222 u64 file_offset; 223 u64 sz; 224}; 225 226#define PERF_AUXTRACE_INDEX_ENTRY_COUNT 256 227 228/** 229 * struct auxtrace_index - index of AUX area tracing events within a perf.data 230 * file. 231 * @list: linking a number of arrays of entries 232 * @nr: number of entries 233 * @entries: array of entries 234 */ 235struct auxtrace_index { 236 struct list_head list; 237 size_t nr; 238 struct auxtrace_index_entry entries[PERF_AUXTRACE_INDEX_ENTRY_COUNT]; 239}; 240 241 HEADER_STAT = 19, 242 243This is merely a flag signifying that the data section contains data 244recorded from perf stat record. 245 246 HEADER_CACHE = 20, 247 248Description of the cache hierarchy. Based on the Linux sysfs format 249in /sys/devices/system/cpu/cpu*/cache/ 250 251 u32 version Currently always 1 252 u32 number_of_cache_levels 253 254struct { 255 u32 level; 256 u32 line_size; 257 u32 sets; 258 u32 ways; 259 struct perf_header_string type; 260 struct perf_header_string size; 261 struct perf_header_string map; 262}[number_of_cache_levels]; 263 264 HEADER_SAMPLE_TIME = 21, 265 266Two uint64_t for the time of first sample and the time of last sample. 267 268 other bits are reserved and should ignored for now 269 HEADER_FEAT_BITS = 256, 270 271Attributes 272 273This is an array of perf_event_attrs, each attr_size bytes long, which defines 274each event collected. See perf_event.h or the man page for a detailed 275description. 276 277Data 278 279This section is the bulk of the file. It consist of a stream of perf_events 280describing events. This matches the format generated by the kernel. 281See perf_event.h or the manpage for a detailed description. 282 283Some notes on parsing: 284 285Ordering 286 287The events are not necessarily in time stamp order, as they can be 288collected in parallel on different CPUs. If the events should be 289processed in time order they need to be sorted first. It is possible 290to only do a partial sort using the FINISHED_ROUND event header (see 291below). perf record guarantees that there is no reordering over a 292FINISHED_ROUND. 293 294ID vs IDENTIFIER 295 296When the event stream contains multiple events each event is identified 297by an ID. This can be either through the PERF_SAMPLE_ID or the 298PERF_SAMPLE_IDENTIFIER header. The PERF_SAMPLE_IDENTIFIER header is 299at a fixed offset from the event header, which allows reliable 300parsing of the header. Relying on ID may be ambiguous. 301IDENTIFIER is only supported by newer Linux kernels. 302 303Perf record specific events: 304 305In addition to the kernel generated event types perf record adds its 306own event types (in addition it also synthesizes some kernel events, 307for example MMAP events) 308 309 PERF_RECORD_USER_TYPE_START = 64, 310 PERF_RECORD_HEADER_ATTR = 64, 311 312struct attr_event { 313 struct perf_event_header header; 314 struct perf_event_attr attr; 315 uint64_t id[]; 316}; 317 318 PERF_RECORD_HEADER_EVENT_TYPE = 65, /* deprecated */ 319 320#define MAX_EVENT_NAME 64 321 322struct perf_trace_event_type { 323 uint64_t event_id; 324 char name[MAX_EVENT_NAME]; 325}; 326 327struct event_type_event { 328 struct perf_event_header header; 329 struct perf_trace_event_type event_type; 330}; 331 332 333 PERF_RECORD_HEADER_TRACING_DATA = 66, 334 335Describe me 336 337struct tracing_data_event { 338 struct perf_event_header header; 339 uint32_t size; 340}; 341 342 PERF_RECORD_HEADER_BUILD_ID = 67, 343 344Define a ELF build ID for a referenced executable. 345 346 struct build_id_event; /* See above */ 347 348 PERF_RECORD_FINISHED_ROUND = 68, 349 350No event reordering over this header. No payload. 351 352 PERF_RECORD_ID_INDEX = 69, 353 354Map event ids to CPUs and TIDs. 355 356struct id_index_entry { 357 uint64_t id; 358 uint64_t idx; 359 uint64_t cpu; 360 uint64_t tid; 361}; 362 363struct id_index_event { 364 struct perf_event_header header; 365 uint64_t nr; 366 struct id_index_entry entries[nr]; 367}; 368 369 PERF_RECORD_AUXTRACE_INFO = 70, 370 371Auxtrace type specific information. Describe me 372 373struct auxtrace_info_event { 374 struct perf_event_header header; 375 uint32_t type; 376 uint32_t reserved__; /* For alignment */ 377 uint64_t priv[]; 378}; 379 380 PERF_RECORD_AUXTRACE = 71, 381 382Defines auxtrace data. Followed by the actual data. The contents of 383the auxtrace data is dependent on the event and the CPU. For example 384for Intel Processor Trace it contains Processor Trace data generated 385by the CPU. 386 387struct auxtrace_event { 388 struct perf_event_header header; 389 uint64_t size; 390 uint64_t offset; 391 uint64_t reference; 392 uint32_t idx; 393 uint32_t tid; 394 uint32_t cpu; 395 uint32_t reserved__; /* For alignment */ 396}; 397 398struct aux_event { 399 struct perf_event_header header; 400 uint64_t aux_offset; 401 uint64_t aux_size; 402 uint64_t flags; 403}; 404 405 PERF_RECORD_AUXTRACE_ERROR = 72, 406 407Describes an error in hardware tracing 408 409enum auxtrace_error_type { 410 PERF_AUXTRACE_ERROR_ITRACE = 1, 411 PERF_AUXTRACE_ERROR_MAX 412}; 413 414#define MAX_AUXTRACE_ERROR_MSG 64 415 416struct auxtrace_error_event { 417 struct perf_event_header header; 418 uint32_t type; 419 uint32_t code; 420 uint32_t cpu; 421 uint32_t pid; 422 uint32_t tid; 423 uint32_t reserved__; /* For alignment */ 424 uint64_t ip; 425 char msg[MAX_AUXTRACE_ERROR_MSG]; 426}; 427 428 PERF_RECORD_HEADER_FEATURE = 80, 429 430Describes a header feature. These are records used in pipe-mode that 431contain information that otherwise would be in perf.data file's header. 432 433Event types 434 435Define the event attributes with their IDs. 436 437An array bound by the perf_file_section size. 438 439 struct { 440 struct perf_event_attr attr; /* Size defined by header.attr_size */ 441 struct perf_file_section ids; 442 } 443 444ids points to a array of uint64_t defining the ids for event attr attr. 445 446Pipe-mode data 447 448Pipe-mode avoid seeks in the file by removing the perf_file_section and flags 449from the struct perf_header. The trimmed header is: 450 451struct perf_pipe_file_header { 452 u64 magic; 453 u64 size; 454}; 455 456The information about attrs, data, and event_types is instead in the 457synthesized events PERF_RECORD_ATTR, PERF_RECORD_HEADER_TRACING_DATA, 458PERF_RECORD_HEADER_EVENT_TYPE, and PERF_RECORD_HEADER_FEATURE 459that are generated by perf record in pipe-mode. 460 461 462References: 463 464include/uapi/linux/perf_event.h 465 466This is the canonical description of the kernel generated perf_events 467and the perf_event_attrs. 468 469perf_events manpage 470 471A manpage describing perf_event and perf_event_attr is here: 472http://web.eece.maine.edu/~vweaver/projects/perf_events/programming.html 473This tends to be slightly behind the kernel include, but has better 474descriptions. An (typically older) version of the man page may be 475included with the standard Linux man pages, available with "man 476perf_events" 477 478pmu-tools 479 480https://github.com/andikleen/pmu-tools/tree/master/parser 481 482A definition of the perf.data format in python "construct" format is available 483in pmu-tools parser. This allows to read perf.data from python and dump it. 484 485quipper 486 487The quipper C++ parser is available at 488https://chromium.googlesource.com/chromiumos/platform2 489 490It is under the chromiumos-wide-profiling/ subdirectory. This library can 491convert a perf data file to a protobuf and vice versa. 492 493Unfortunately this parser tends to be many versions behind and may not be able 494to parse data files generated by recent perf. 495