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 46For each of the optional features a perf_file_section it placed after the data 47section if the feature bit is set in the perf_header flags bitset. The 48respective perf_file_section points to the data of the additional header and 49defines its size. 50 51Some headers consist of strings, which are defined like this: 52 53struct perf_header_string { 54 uint32_t len; 55 char string[len]; /* zero terminated */ 56}; 57 58Some headers consist of a sequence of strings, which start with a 59 60struct perf_header_string_list { 61 uint32_t nr; 62 struct perf_header_string strings[nr]; /* variable length records */ 63}; 64 65The bits are the flags bits in a 256 bit bitmap starting with 66flags. These define the valid bits: 67 68 HEADER_RESERVED = 0, /* always cleared */ 69 HEADER_FIRST_FEATURE = 1, 70 HEADER_TRACING_DATA = 1, 71 72Describe me. 73 74 HEADER_BUILD_ID = 2, 75 76The header consists of an sequence of build_id_event. The size of each record 77is defined by header.size (see perf_event.h). Each event defines a ELF build id 78for a executable file name for a pid. An ELF build id is a unique identifier 79assigned by the linker to an executable. 80 81struct build_id_event { 82 struct perf_event_header header; 83 pid_t pid; 84 uint8_t build_id[24]; 85 char filename[header.size - offsetof(struct build_id_event, filename)]; 86}; 87 88 HEADER_HOSTNAME = 3, 89 90A perf_header_string with the hostname where the data was collected 91(uname -n) 92 93 HEADER_OSRELEASE = 4, 94 95A perf_header_string with the os release where the data was collected 96(uname -r) 97 98 HEADER_VERSION = 5, 99 100A perf_header_string with the perf user tool version where the 101data was collected. This is the same as the version of the source tree 102the perf tool was built from. 103 104 HEADER_ARCH = 6, 105 106A perf_header_string with the CPU architecture (uname -m) 107 108 HEADER_NRCPUS = 7, 109 110A structure defining the number of CPUs. 111 112struct nr_cpus { 113 uint32_t nr_cpus_available; /* CPUs not yet onlined */ 114 uint32_t nr_cpus_online; 115}; 116 117 HEADER_CPUDESC = 8, 118 119A perf_header_string with description of the CPU. On x86 this is the model name 120in /proc/cpuinfo 121 122 HEADER_CPUID = 9, 123 124A perf_header_string with the exact CPU type. On x86 this is 125vendor,family,model,stepping. For example: GenuineIntel,6,69,1 126 127 HEADER_TOTAL_MEM = 10, 128 129An uint64_t with the total memory in bytes. 130 131 HEADER_CMDLINE = 11, 132 133A perf_header_string_list with the perf arg-vector used to collect the data. 134 135 HEADER_EVENT_DESC = 12, 136 137Another description of the perf_event_attrs, more detailed than header.attrs 138including IDs and names. See perf_event.h or the man page for a description 139of a struct perf_event_attr. 140 141struct { 142 uint32_t nr; /* number of events */ 143 uint32_t attr_size; /* size of each perf_event_attr */ 144 struct { 145 struct perf_event_attr attr; /* size of attr_size */ 146 uint32_t nr_ids; 147 struct perf_header_string event_string; 148 uint64_t ids[nr_ids]; 149 } events[nr]; /* Variable length records */ 150}; 151 152 HEADER_CPU_TOPOLOGY = 13, 153 154String lists defining the core and CPU threads topology. 155The string lists are followed by a variable length array 156which contains core_id, die_id (for x86) and socket_id of each cpu. 157The number of entries can be determined by the size of the 158section minus the sizes of both string lists. 159 160struct { 161 struct perf_header_string_list cores; /* Variable length */ 162 struct perf_header_string_list threads; /* Variable length */ 163 struct { 164 uint32_t core_id; 165 uint32_t die_id; 166 uint32_t socket_id; 167 } cpus[nr]; /* Variable length records */ 168}; 169 170Example: 171 sibling cores : 0-8 172 sibling dies : 0-3 173 sibling dies : 4-7 174 sibling threads : 0-1 175 sibling threads : 2-3 176 sibling threads : 4-5 177 sibling threads : 6-7 178 179 HEADER_NUMA_TOPOLOGY = 14, 180 181 A list of NUMA node descriptions 182 183struct { 184 uint32_t nr; 185 struct { 186 uint32_t nodenr; 187 uint64_t mem_total; 188 uint64_t mem_free; 189 struct perf_header_string cpus; 190 } nodes[nr]; /* Variable length records */ 191}; 192 193 HEADER_BRANCH_STACK = 15, 194 195Not implemented in perf. 196 197 HEADER_PMU_MAPPINGS = 16, 198 199 A list of PMU structures, defining the different PMUs supported by perf. 200 201struct { 202 uint32_t nr; 203 struct pmu { 204 uint32_t pmu_type; 205 struct perf_header_string pmu_name; 206 } [nr]; /* Variable length records */ 207}; 208 209 HEADER_GROUP_DESC = 17, 210 211 Description of counter groups ({...} in perf syntax) 212 213struct { 214 uint32_t nr; 215 struct { 216 struct perf_header_string string; 217 uint32_t leader_idx; 218 uint32_t nr_members; 219 } [nr]; /* Variable length records */ 220}; 221 222 HEADER_AUXTRACE = 18, 223 224Define additional auxtrace areas in the perf.data. auxtrace is used to store 225undecoded hardware tracing information, such as Intel Processor Trace data. 226 227/** 228 * struct auxtrace_index_entry - indexes a AUX area tracing event within a 229 * perf.data file. 230 * @file_offset: offset within the perf.data file 231 * @sz: size of the event 232 */ 233struct auxtrace_index_entry { 234 u64 file_offset; 235 u64 sz; 236}; 237 238#define PERF_AUXTRACE_INDEX_ENTRY_COUNT 256 239 240/** 241 * struct auxtrace_index - index of AUX area tracing events within a perf.data 242 * file. 243 * @list: linking a number of arrays of entries 244 * @nr: number of entries 245 * @entries: array of entries 246 */ 247struct auxtrace_index { 248 struct list_head list; 249 size_t nr; 250 struct auxtrace_index_entry entries[PERF_AUXTRACE_INDEX_ENTRY_COUNT]; 251}; 252 253 HEADER_STAT = 19, 254 255This is merely a flag signifying that the data section contains data 256recorded from perf stat record. 257 258 HEADER_CACHE = 20, 259 260Description of the cache hierarchy. Based on the Linux sysfs format 261in /sys/devices/system/cpu/cpu*/cache/ 262 263 u32 version Currently always 1 264 u32 number_of_cache_levels 265 266struct { 267 u32 level; 268 u32 line_size; 269 u32 sets; 270 u32 ways; 271 struct perf_header_string type; 272 struct perf_header_string size; 273 struct perf_header_string map; 274}[number_of_cache_levels]; 275 276 HEADER_SAMPLE_TIME = 21, 277 278Two uint64_t for the time of first sample and the time of last sample. 279 280 HEADER_SAMPLE_TOPOLOGY = 22, 281 282Physical memory map and its node assignments. 283 284The format of data in MEM_TOPOLOGY is as follows: 285 286 0 - version | for future changes 287 8 - block_size_bytes | /sys/devices/system/memory/block_size_bytes 288 16 - count | number of nodes 289 290For each node we store map of physical indexes: 291 292 32 - node id | node index 293 40 - size | size of bitmap 294 48 - bitmap | bitmap of memory indexes that belongs to node 295 | /sys/devices/system/node/node<NODE>/memory<INDEX> 296 297The MEM_TOPOLOGY can be displayed with following command: 298 299$ perf report --header-only -I 300... 301# memory nodes (nr 1, block size 0x8000000): 302# 0 [7G]: 0-23,32-69 303 304 HEADER_CLOCKID = 23, 305 306One uint64_t for the clockid frequency, specified, for instance, via 'perf 307record -k' (see clock_gettime()), to enable timestamps derived metrics 308conversion into wall clock time on the reporting stage. 309 310 HEADER_DIR_FORMAT = 24, 311 312The data files layout is described by HEADER_DIR_FORMAT feature. Currently it 313holds only version number (1): 314 315 uint64_t version; 316 317The current version holds only version value (1) means that data files: 318 319- Follow the 'data.*' name format. 320 321- Contain raw events data in standard perf format as read from kernel (and need 322 to be sorted) 323 324Future versions are expected to describe different data files layout according 325to special needs. 326 327 HEADER_BPF_PROG_INFO = 25, 328 329struct bpf_prog_info_linear, which contains detailed information about 330a BPF program, including type, id, tag, jited/xlated instructions, etc. 331 332 HEADER_BPF_BTF = 26, 333 334Contains BPF Type Format (BTF). For more information about BTF, please 335refer to Documentation/bpf/btf.rst. 336 337struct { 338 u32 id; 339 u32 data_size; 340 char data[]; 341}; 342 343 HEADER_COMPRESSED = 27, 344 345struct { 346 u32 version; 347 u32 type; 348 u32 level; 349 u32 ratio; 350 u32 mmap_len; 351}; 352 353Indicates that trace contains records of PERF_RECORD_COMPRESSED type 354that have perf_events records in compressed form. 355 356 other bits are reserved and should ignored for now 357 HEADER_FEAT_BITS = 256, 358 359Attributes 360 361This is an array of perf_event_attrs, each attr_size bytes long, which defines 362each event collected. See perf_event.h or the man page for a detailed 363description. 364 365Data 366 367This section is the bulk of the file. It consist of a stream of perf_events 368describing events. This matches the format generated by the kernel. 369See perf_event.h or the manpage for a detailed description. 370 371Some notes on parsing: 372 373Ordering 374 375The events are not necessarily in time stamp order, as they can be 376collected in parallel on different CPUs. If the events should be 377processed in time order they need to be sorted first. It is possible 378to only do a partial sort using the FINISHED_ROUND event header (see 379below). perf record guarantees that there is no reordering over a 380FINISHED_ROUND. 381 382ID vs IDENTIFIER 383 384When the event stream contains multiple events each event is identified 385by an ID. This can be either through the PERF_SAMPLE_ID or the 386PERF_SAMPLE_IDENTIFIER header. The PERF_SAMPLE_IDENTIFIER header is 387at a fixed offset from the event header, which allows reliable 388parsing of the header. Relying on ID may be ambiguous. 389IDENTIFIER is only supported by newer Linux kernels. 390 391Perf record specific events: 392 393In addition to the kernel generated event types perf record adds its 394own event types (in addition it also synthesizes some kernel events, 395for example MMAP events) 396 397 PERF_RECORD_USER_TYPE_START = 64, 398 PERF_RECORD_HEADER_ATTR = 64, 399 400struct attr_event { 401 struct perf_event_header header; 402 struct perf_event_attr attr; 403 uint64_t id[]; 404}; 405 406 PERF_RECORD_HEADER_EVENT_TYPE = 65, /* deprecated */ 407 408#define MAX_EVENT_NAME 64 409 410struct perf_trace_event_type { 411 uint64_t event_id; 412 char name[MAX_EVENT_NAME]; 413}; 414 415struct event_type_event { 416 struct perf_event_header header; 417 struct perf_trace_event_type event_type; 418}; 419 420 421 PERF_RECORD_HEADER_TRACING_DATA = 66, 422 423Describe me 424 425struct tracing_data_event { 426 struct perf_event_header header; 427 uint32_t size; 428}; 429 430 PERF_RECORD_HEADER_BUILD_ID = 67, 431 432Define a ELF build ID for a referenced executable. 433 434 struct build_id_event; /* See above */ 435 436 PERF_RECORD_FINISHED_ROUND = 68, 437 438No event reordering over this header. No payload. 439 440 PERF_RECORD_ID_INDEX = 69, 441 442Map event ids to CPUs and TIDs. 443 444struct id_index_entry { 445 uint64_t id; 446 uint64_t idx; 447 uint64_t cpu; 448 uint64_t tid; 449}; 450 451struct id_index_event { 452 struct perf_event_header header; 453 uint64_t nr; 454 struct id_index_entry entries[nr]; 455}; 456 457 PERF_RECORD_AUXTRACE_INFO = 70, 458 459Auxtrace type specific information. Describe me 460 461struct auxtrace_info_event { 462 struct perf_event_header header; 463 uint32_t type; 464 uint32_t reserved__; /* For alignment */ 465 uint64_t priv[]; 466}; 467 468 PERF_RECORD_AUXTRACE = 71, 469 470Defines auxtrace data. Followed by the actual data. The contents of 471the auxtrace data is dependent on the event and the CPU. For example 472for Intel Processor Trace it contains Processor Trace data generated 473by the CPU. 474 475struct auxtrace_event { 476 struct perf_event_header header; 477 uint64_t size; 478 uint64_t offset; 479 uint64_t reference; 480 uint32_t idx; 481 uint32_t tid; 482 uint32_t cpu; 483 uint32_t reserved__; /* For alignment */ 484}; 485 486struct aux_event { 487 struct perf_event_header header; 488 uint64_t aux_offset; 489 uint64_t aux_size; 490 uint64_t flags; 491}; 492 493 PERF_RECORD_AUXTRACE_ERROR = 72, 494 495Describes an error in hardware tracing 496 497enum auxtrace_error_type { 498 PERF_AUXTRACE_ERROR_ITRACE = 1, 499 PERF_AUXTRACE_ERROR_MAX 500}; 501 502#define MAX_AUXTRACE_ERROR_MSG 64 503 504struct auxtrace_error_event { 505 struct perf_event_header header; 506 uint32_t type; 507 uint32_t code; 508 uint32_t cpu; 509 uint32_t pid; 510 uint32_t tid; 511 uint32_t reserved__; /* For alignment */ 512 uint64_t ip; 513 char msg[MAX_AUXTRACE_ERROR_MSG]; 514}; 515 516 PERF_RECORD_HEADER_FEATURE = 80, 517 518Describes a header feature. These are records used in pipe-mode that 519contain information that otherwise would be in perf.data file's header. 520 521 PERF_RECORD_COMPRESSED = 81, 522 523struct compressed_event { 524 struct perf_event_header header; 525 char data[]; 526}; 527 528The header is followed by compressed data frame that can be decompressed 529into array of perf trace records. The size of the entire compressed event 530record including the header is limited by the max value of header.size. 531 532Event types 533 534Define the event attributes with their IDs. 535 536An array bound by the perf_file_section size. 537 538 struct { 539 struct perf_event_attr attr; /* Size defined by header.attr_size */ 540 struct perf_file_section ids; 541 } 542 543ids points to a array of uint64_t defining the ids for event attr attr. 544 545Pipe-mode data 546 547Pipe-mode avoid seeks in the file by removing the perf_file_section and flags 548from the struct perf_header. The trimmed header is: 549 550struct perf_pipe_file_header { 551 u64 magic; 552 u64 size; 553}; 554 555The information about attrs, data, and event_types is instead in the 556synthesized events PERF_RECORD_ATTR, PERF_RECORD_HEADER_TRACING_DATA, 557PERF_RECORD_HEADER_EVENT_TYPE, and PERF_RECORD_HEADER_FEATURE 558that are generated by perf record in pipe-mode. 559 560 561References: 562 563include/uapi/linux/perf_event.h 564 565This is the canonical description of the kernel generated perf_events 566and the perf_event_attrs. 567 568perf_events manpage 569 570A manpage describing perf_event and perf_event_attr is here: 571http://web.eece.maine.edu/~vweaver/projects/perf_events/programming.html 572This tends to be slightly behind the kernel include, but has better 573descriptions. An (typically older) version of the man page may be 574included with the standard Linux man pages, available with "man 575perf_events" 576 577pmu-tools 578 579https://github.com/andikleen/pmu-tools/tree/master/parser 580 581A definition of the perf.data format in python "construct" format is available 582in pmu-tools parser. This allows to read perf.data from python and dump it. 583 584quipper 585 586The quipper C++ parser is available at 587http://github.com/google/perf_data_converter/tree/master/src/quipper 588 589