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 is 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 kilobytes. 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 154struct { 155 /* 156 * First revision of HEADER_CPU_TOPOLOGY 157 * 158 * See 'struct perf_header_string_list' definition earlier 159 * in this file. 160 */ 161 162 struct perf_header_string_list cores; /* Variable length */ 163 struct perf_header_string_list threads; /* Variable length */ 164 165 /* 166 * Second revision of HEADER_CPU_TOPOLOGY, older tools 167 * will not consider what comes next 168 */ 169 170 struct { 171 uint32_t core_id; 172 uint32_t socket_id; 173 } cpus[nr]; /* Variable length records */ 174 /* 'nr' comes from previously processed HEADER_NRCPUS's nr_cpu_avail */ 175 176 /* 177 * Third revision of HEADER_CPU_TOPOLOGY, older tools 178 * will not consider what comes next 179 */ 180 181 struct perf_header_string_list dies; /* Variable length */ 182 uint32_t die_id[nr_cpus_avail]; /* from previously processed HEADER_NR_CPUS, VLA */ 183}; 184 185Example: 186 sibling sockets : 0-8 187 sibling dies : 0-3 188 sibling dies : 4-7 189 sibling threads : 0-1 190 sibling threads : 2-3 191 sibling threads : 4-5 192 sibling threads : 6-7 193 194 HEADER_NUMA_TOPOLOGY = 14, 195 196 A list of NUMA node descriptions 197 198struct { 199 uint32_t nr; 200 struct { 201 uint32_t nodenr; 202 uint64_t mem_total; 203 uint64_t mem_free; 204 struct perf_header_string cpus; 205 } nodes[nr]; /* Variable length records */ 206}; 207 208 HEADER_BRANCH_STACK = 15, 209 210Not implemented in perf. 211 212 HEADER_PMU_MAPPINGS = 16, 213 214 A list of PMU structures, defining the different PMUs supported by perf. 215 216struct { 217 uint32_t nr; 218 struct pmu { 219 uint32_t pmu_type; 220 struct perf_header_string pmu_name; 221 } [nr]; /* Variable length records */ 222}; 223 224 HEADER_GROUP_DESC = 17, 225 226 Description of counter groups ({...} in perf syntax) 227 228struct { 229 uint32_t nr; 230 struct { 231 struct perf_header_string string; 232 uint32_t leader_idx; 233 uint32_t nr_members; 234 } [nr]; /* Variable length records */ 235}; 236 237 HEADER_AUXTRACE = 18, 238 239Define additional auxtrace areas in the perf.data. auxtrace is used to store 240undecoded hardware tracing information, such as Intel Processor Trace data. 241 242/** 243 * struct auxtrace_index_entry - indexes a AUX area tracing event within a 244 * perf.data file. 245 * @file_offset: offset within the perf.data file 246 * @sz: size of the event 247 */ 248struct auxtrace_index_entry { 249 u64 file_offset; 250 u64 sz; 251}; 252 253#define PERF_AUXTRACE_INDEX_ENTRY_COUNT 256 254 255/** 256 * struct auxtrace_index - index of AUX area tracing events within a perf.data 257 * file. 258 * @list: linking a number of arrays of entries 259 * @nr: number of entries 260 * @entries: array of entries 261 */ 262struct auxtrace_index { 263 struct list_head list; 264 size_t nr; 265 struct auxtrace_index_entry entries[PERF_AUXTRACE_INDEX_ENTRY_COUNT]; 266}; 267 268 HEADER_STAT = 19, 269 270This is merely a flag signifying that the data section contains data 271recorded from perf stat record. 272 273 HEADER_CACHE = 20, 274 275Description of the cache hierarchy. Based on the Linux sysfs format 276in /sys/devices/system/cpu/cpu*/cache/ 277 278 u32 version Currently always 1 279 u32 number_of_cache_levels 280 281struct { 282 u32 level; 283 u32 line_size; 284 u32 sets; 285 u32 ways; 286 struct perf_header_string type; 287 struct perf_header_string size; 288 struct perf_header_string map; 289}[number_of_cache_levels]; 290 291 HEADER_SAMPLE_TIME = 21, 292 293Two uint64_t for the time of first sample and the time of last sample. 294 295 HEADER_SAMPLE_TOPOLOGY = 22, 296 297Physical memory map and its node assignments. 298 299The format of data in MEM_TOPOLOGY is as follows: 300 301 u64 version; // Currently 1 302 u64 block_size_bytes; // /sys/devices/system/memory/block_size_bytes 303 u64 count; // number of nodes 304 305struct memory_node { 306 u64 node_id; // node index 307 u64 size; // size of bitmap 308 struct bitmap { 309 /* size of bitmap again */ 310 u64 bitmapsize; 311 /* bitmap of memory indexes that belongs to node */ 312 /* /sys/devices/system/node/node<NODE>/memory<INDEX> */ 313 u64 entries[(bitmapsize/64)+1]; 314 } 315}[count]; 316 317The MEM_TOPOLOGY can be displayed with following command: 318 319$ perf report --header-only -I 320... 321# memory nodes (nr 1, block size 0x8000000): 322# 0 [7G]: 0-23,32-69 323 324 HEADER_CLOCKID = 23, 325 326One uint64_t for the clockid frequency, specified, for instance, via 'perf 327record -k' (see clock_gettime()), to enable timestamps derived metrics 328conversion into wall clock time on the reporting stage. 329 330 HEADER_DIR_FORMAT = 24, 331 332The data files layout is described by HEADER_DIR_FORMAT feature. Currently it 333holds only version number (1): 334 335 uint64_t version; 336 337The current version holds only version value (1) means that data files: 338 339- Follow the 'data.*' name format. 340 341- Contain raw events data in standard perf format as read from kernel (and need 342 to be sorted) 343 344Future versions are expected to describe different data files layout according 345to special needs. 346 347 HEADER_BPF_PROG_INFO = 25, 348 349struct perf_bpil, which contains detailed information about 350a BPF program, including type, id, tag, jited/xlated instructions, etc. 351The format of data in HEADER_BPF_PROG_INFO is as follows: 352 u32 count 353 354 struct perf_bpil { 355 u32 info_len; /* size of struct bpf_prog_info, when the tool is compiled */ 356 u32 data_len; /* total bytes allocated for data, round up to 8 bytes */ 357 u64 arrays; /* which arrays are included in data */ 358 struct bpf_prog_info info; 359 u8 data[]; 360 }[count]; 361 362 HEADER_BPF_BTF = 26, 363 364Contains BPF Type Format (BTF). For more information about BTF, please 365refer to Documentation/bpf/btf.rst. 366 367struct { 368 u32 id; 369 u32 data_size; 370 char data[]; 371}; 372 373 HEADER_COMPRESSED = 27, 374 375struct { 376 u32 version; 377 u32 type; 378 u32 level; 379 u32 ratio; 380 u32 mmap_len; 381}; 382 383Indicates that trace contains records of PERF_RECORD_COMPRESSED2 type 384that have perf_events records in compressed form. 385 386 HEADER_CPU_PMU_CAPS = 28, 387 388 A list of cpu PMU capabilities. The format of data is as below. 389 390struct { 391 u32 nr_cpu_pmu_caps; 392 { 393 char name[]; 394 char value[]; 395 } [nr_cpu_pmu_caps] 396}; 397 398 399Example: 400 cpu pmu capabilities: branches=32, max_precise=3, pmu_name=icelake 401 402 HEADER_CLOCK_DATA = 29, 403 404 Contains clock id and its reference time together with wall clock 405 time taken at the 'same time', both values are in nanoseconds. 406 The format of data is as below. 407 408struct { 409 u32 version; /* version = 1 */ 410 u32 clockid; 411 u64 wall_clock_ns; 412 u64 clockid_time_ns; 413}; 414 415 HEADER_HYBRID_TOPOLOGY = 30, 416 417Indicate the hybrid CPUs. The format of data is as below. 418 419struct { 420 u32 nr; 421 struct { 422 char pmu_name[]; 423 char cpus[]; 424 } [nr]; /* Variable length records */ 425}; 426 427Example: 428 hybrid cpu system: 429 cpu_core cpu list : 0-15 430 cpu_atom cpu list : 16-23 431 432 HEADER_PMU_CAPS = 31, 433 434 List of pmu capabilities (except cpu pmu which is already 435 covered by HEADER_CPU_PMU_CAPS). Note that hybrid cpu pmu 436 capabilities are also stored here. 437 438struct { 439 u32 nr_pmu; 440 struct { 441 u32 nr_caps; 442 { 443 char name[]; 444 char value[]; 445 } [nr_caps]; 446 char pmu_name[]; 447 } [nr_pmu]; 448}; 449 450 HEADER_CPU_DOMAIN_INFO = 32, 451 452List of cpu-domain relation info. The format of the data is as below. 453 454struct domain_info { 455 int domain; 456 char dname[]; 457 char cpumask[]; 458 char cpulist[]; 459}; 460 461struct cpu_domain_info { 462 int cpu; 463 int nr_domains; 464 struct domain_info domains[]; 465}; 466 467 other bits are reserved and should ignored for now 468 HEADER_FEAT_BITS = 256, 469 470Attributes 471 472This is an array of perf_event_attrs, each attr_size bytes long, which defines 473each event collected. See perf_event.h or the man page for a detailed 474description. 475 476Data 477 478This section is the bulk of the file. It consist of a stream of perf_events 479describing events. This matches the format generated by the kernel. 480See perf_event.h or the manpage for a detailed description. 481 482Some notes on parsing: 483 484Ordering 485 486The events are not necessarily in time stamp order, as they can be 487collected in parallel on different CPUs. If the events should be 488processed in time order they need to be sorted first. It is possible 489to only do a partial sort using the FINISHED_ROUND event header (see 490below). perf record guarantees that there is no reordering over a 491FINISHED_ROUND. 492 493ID vs IDENTIFIER 494 495When the event stream contains multiple events each event is identified 496by an ID. This can be either through the PERF_SAMPLE_ID or the 497PERF_SAMPLE_IDENTIFIER header. The PERF_SAMPLE_IDENTIFIER header is 498at a fixed offset from the event header, which allows reliable 499parsing of the header. Relying on ID may be ambiguous. 500IDENTIFIER is only supported by newer Linux kernels. 501 502Perf record specific events: 503 504In addition to the kernel generated event types perf record adds its 505own event types (in addition it also synthesizes some kernel events, 506for example MMAP events) 507 508 PERF_RECORD_USER_TYPE_START = 64, 509 PERF_RECORD_HEADER_ATTR = 64, 510 511struct attr_event { 512 struct perf_event_header header; 513 struct perf_event_attr attr; 514 uint64_t id[]; 515}; 516 517 PERF_RECORD_HEADER_EVENT_TYPE = 65, /* deprecated */ 518 519#define MAX_EVENT_NAME 64 520 521struct perf_trace_event_type { 522 uint64_t event_id; 523 char name[MAX_EVENT_NAME]; 524}; 525 526struct event_type_event { 527 struct perf_event_header header; 528 struct perf_trace_event_type event_type; 529}; 530 531 532 PERF_RECORD_HEADER_TRACING_DATA = 66, 533 534Describe me 535 536struct tracing_data_event { 537 struct perf_event_header header; 538 uint32_t size; 539}; 540 541 PERF_RECORD_HEADER_BUILD_ID = 67, 542 543Define a ELF build ID for a referenced executable. 544 545 struct build_id_event; /* See above */ 546 547 PERF_RECORD_FINISHED_ROUND = 68, 548 549No event reordering over this header. No payload. 550 551 PERF_RECORD_ID_INDEX = 69, 552 553Map event ids to CPUs and TIDs. 554 555struct id_index_entry { 556 uint64_t id; 557 uint64_t idx; 558 uint64_t cpu; 559 uint64_t tid; 560}; 561 562struct id_index_event { 563 struct perf_event_header header; 564 uint64_t nr; 565 struct id_index_entry entries[nr]; 566}; 567 568 PERF_RECORD_AUXTRACE_INFO = 70, 569 570Auxtrace type specific information. Describe me 571 572struct auxtrace_info_event { 573 struct perf_event_header header; 574 uint32_t type; 575 uint32_t reserved__; /* For alignment */ 576 uint64_t priv[]; 577}; 578 579 PERF_RECORD_AUXTRACE = 71, 580 581Defines auxtrace data. Followed by the actual data. The contents of 582the auxtrace data is dependent on the event and the CPU. For example 583for Intel Processor Trace it contains Processor Trace data generated 584by the CPU. 585 586struct auxtrace_event { 587 struct perf_event_header header; 588 uint64_t size; 589 uint64_t offset; 590 uint64_t reference; 591 uint32_t idx; 592 uint32_t tid; 593 uint32_t cpu; 594 uint32_t reserved__; /* For alignment */ 595}; 596 597struct aux_event { 598 struct perf_event_header header; 599 uint64_t aux_offset; 600 uint64_t aux_size; 601 uint64_t flags; 602}; 603 604 PERF_RECORD_AUXTRACE_ERROR = 72, 605 606Describes an error in hardware tracing 607 608enum auxtrace_error_type { 609 PERF_AUXTRACE_ERROR_ITRACE = 1, 610 PERF_AUXTRACE_ERROR_MAX 611}; 612 613#define MAX_AUXTRACE_ERROR_MSG 64 614 615struct auxtrace_error_event { 616 struct perf_event_header header; 617 uint32_t type; 618 uint32_t code; 619 uint32_t cpu; 620 uint32_t pid; 621 uint32_t tid; 622 uint32_t reserved__; /* For alignment */ 623 uint64_t ip; 624 char msg[MAX_AUXTRACE_ERROR_MSG]; 625}; 626 627 PERF_RECORD_HEADER_FEATURE = 80, 628 629Describes a header feature. These are records used in pipe-mode that 630contain information that otherwise would be in perf.data file's header. 631 632 PERF_RECORD_COMPRESSED = 81, /* deprecated */ 633 634The header is followed by compressed data frame that can be decompressed 635into array of perf trace records. The size of the entire compressed event 636record including the header is limited by the max value of header.size. 637 638It is deprecated and new files should use PERF_RECORD_COMPRESSED2 to gurantee 6398-byte alignment. 640 641struct compressed_event { 642 struct perf_event_header header; 643 char data[]; 644}; 645 646 PERF_RECORD_FINISHED_INIT = 82, 647 648Marks the end of records for the system, pre-existing threads in system wide 649sessions, etc. Those are the ones prefixed PERF_RECORD_USER_*. 650 651This is used, for instance, to 'perf inject' events after init and before 652regular events, those emitted by the kernel, to support combining guest and 653host records. 654 655 PERF_RECORD_COMPRESSED2 = 83, 656 6578-byte aligned version of `PERF_RECORD_COMPRESSED`. `header.size` indicates the 658total record size, including padding for 8-byte alignment, and `data_size` 659specifies the actual size of the compressed data. 660 661struct perf_record_compressed2 { 662 struct perf_event_header header; 663 __u64 data_size; 664 char data[]; 665}; 666 667Event types 668 669Define the event attributes with their IDs. 670 671An array bound by the perf_file_section size. 672 673 struct { 674 struct perf_event_attr attr; /* Size defined by header.attr_size */ 675 struct perf_file_section ids; 676 } 677 678ids points to a array of uint64_t defining the ids for event attr attr. 679 680Pipe-mode data 681 682Pipe-mode avoid seeks in the file by removing the perf_file_section and flags 683from the struct perf_header. The trimmed header is: 684 685struct perf_pipe_file_header { 686 u64 magic; 687 u64 size; 688}; 689 690The information about attrs, data, and event_types is instead in the 691synthesized events PERF_RECORD_ATTR, PERF_RECORD_HEADER_TRACING_DATA, 692PERF_RECORD_HEADER_EVENT_TYPE, and PERF_RECORD_HEADER_FEATURE 693that are generated by perf record in pipe-mode. 694 695 696References: 697 698include/uapi/linux/perf_event.h 699 700This is the canonical description of the kernel generated perf_events 701and the perf_event_attrs. 702 703perf_events manpage 704 705A manpage describing perf_event and perf_event_attr is here: 706http://web.eece.maine.edu/~vweaver/projects/perf_events/programming.html 707This tends to be slightly behind the kernel include, but has better 708descriptions. An (typically older) version of the man page may be 709included with the standard Linux man pages, available with "man 710perf_events" 711 712pmu-tools 713 714https://github.com/andikleen/pmu-tools/tree/master/parser 715 716A definition of the perf.data format in python "construct" format is available 717in pmu-tools parser. This allows to read perf.data from python and dump it. 718 719quipper 720 721The quipper C++ parser is available at 722http://github.com/google/perf_data_converter/tree/master/src/quipper 723 724