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 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 socket_id; 166 } cpus[nr]; /* Variable length records */ 167}; 168 169Example: 170 sibling cores : 0-3 171 sibling threads : 0-1 172 sibling threads : 2-3 173 174 HEADER_NUMA_TOPOLOGY = 14, 175 176 A list of NUMA node descriptions 177 178struct { 179 uint32_t nr; 180 struct { 181 uint32_t nodenr; 182 uint64_t mem_total; 183 uint64_t mem_free; 184 struct perf_header_string cpus; 185 } nodes[nr]; /* Variable length records */ 186}; 187 188 HEADER_BRANCH_STACK = 15, 189 190Not implemented in perf. 191 192 HEADER_PMU_MAPPINGS = 16, 193 194 A list of PMU structures, defining the different PMUs supported by perf. 195 196struct { 197 uint32_t nr; 198 struct pmu { 199 uint32_t pmu_type; 200 struct perf_header_string pmu_name; 201 } [nr]; /* Variable length records */ 202}; 203 204 HEADER_GROUP_DESC = 17, 205 206 Description of counter groups ({...} in perf syntax) 207 208struct { 209 uint32_t nr; 210 struct { 211 struct perf_header_string string; 212 uint32_t leader_idx; 213 uint32_t nr_members; 214 } [nr]; /* Variable length records */ 215}; 216 217 HEADER_AUXTRACE = 18, 218 219Define additional auxtrace areas in the perf.data. auxtrace is used to store 220undecoded hardware tracing information, such as Intel Processor Trace data. 221 222/** 223 * struct auxtrace_index_entry - indexes a AUX area tracing event within a 224 * perf.data file. 225 * @file_offset: offset within the perf.data file 226 * @sz: size of the event 227 */ 228struct auxtrace_index_entry { 229 u64 file_offset; 230 u64 sz; 231}; 232 233#define PERF_AUXTRACE_INDEX_ENTRY_COUNT 256 234 235/** 236 * struct auxtrace_index - index of AUX area tracing events within a perf.data 237 * file. 238 * @list: linking a number of arrays of entries 239 * @nr: number of entries 240 * @entries: array of entries 241 */ 242struct auxtrace_index { 243 struct list_head list; 244 size_t nr; 245 struct auxtrace_index_entry entries[PERF_AUXTRACE_INDEX_ENTRY_COUNT]; 246}; 247 248 HEADER_STAT = 19, 249 250This is merely a flag signifying that the data section contains data 251recorded from perf stat record. 252 253 HEADER_CACHE = 20, 254 255Description of the cache hierarchy. Based on the Linux sysfs format 256in /sys/devices/system/cpu/cpu*/cache/ 257 258 u32 version Currently always 1 259 u32 number_of_cache_levels 260 261struct { 262 u32 level; 263 u32 line_size; 264 u32 sets; 265 u32 ways; 266 struct perf_header_string type; 267 struct perf_header_string size; 268 struct perf_header_string map; 269}[number_of_cache_levels]; 270 271 HEADER_SAMPLE_TIME = 21, 272 273Two uint64_t for the time of first sample and the time of last sample. 274 275 HEADER_BPF_PROG_INFO = 25, 276 277struct bpf_prog_info_linear, which contains detailed information about 278a BPF program, including type, id, tag, jited/xlated instructions, etc. 279 280 HEADER_BPF_BTF = 26, 281 282Contains BPF Type Format (BTF). For more information about BTF, please 283refer to Documentation/bpf/btf.rst. 284 285struct { 286 u32 id; 287 u32 data_size; 288 char data[]; 289}; 290 291 HEADER_COMPRESSED = 27, 292 293struct { 294 u32 version; 295 u32 type; 296 u32 level; 297 u32 ratio; 298 u32 mmap_len; 299}; 300 301Indicates that trace contains records of PERF_RECORD_COMPRESSED type 302that have perf_events records in compressed form. 303 304 other bits are reserved and should ignored for now 305 HEADER_FEAT_BITS = 256, 306 307Attributes 308 309This is an array of perf_event_attrs, each attr_size bytes long, which defines 310each event collected. See perf_event.h or the man page for a detailed 311description. 312 313Data 314 315This section is the bulk of the file. It consist of a stream of perf_events 316describing events. This matches the format generated by the kernel. 317See perf_event.h or the manpage for a detailed description. 318 319Some notes on parsing: 320 321Ordering 322 323The events are not necessarily in time stamp order, as they can be 324collected in parallel on different CPUs. If the events should be 325processed in time order they need to be sorted first. It is possible 326to only do a partial sort using the FINISHED_ROUND event header (see 327below). perf record guarantees that there is no reordering over a 328FINISHED_ROUND. 329 330ID vs IDENTIFIER 331 332When the event stream contains multiple events each event is identified 333by an ID. This can be either through the PERF_SAMPLE_ID or the 334PERF_SAMPLE_IDENTIFIER header. The PERF_SAMPLE_IDENTIFIER header is 335at a fixed offset from the event header, which allows reliable 336parsing of the header. Relying on ID may be ambiguous. 337IDENTIFIER is only supported by newer Linux kernels. 338 339Perf record specific events: 340 341In addition to the kernel generated event types perf record adds its 342own event types (in addition it also synthesizes some kernel events, 343for example MMAP events) 344 345 PERF_RECORD_USER_TYPE_START = 64, 346 PERF_RECORD_HEADER_ATTR = 64, 347 348struct attr_event { 349 struct perf_event_header header; 350 struct perf_event_attr attr; 351 uint64_t id[]; 352}; 353 354 PERF_RECORD_HEADER_EVENT_TYPE = 65, /* deprecated */ 355 356#define MAX_EVENT_NAME 64 357 358struct perf_trace_event_type { 359 uint64_t event_id; 360 char name[MAX_EVENT_NAME]; 361}; 362 363struct event_type_event { 364 struct perf_event_header header; 365 struct perf_trace_event_type event_type; 366}; 367 368 369 PERF_RECORD_HEADER_TRACING_DATA = 66, 370 371Describe me 372 373struct tracing_data_event { 374 struct perf_event_header header; 375 uint32_t size; 376}; 377 378 PERF_RECORD_HEADER_BUILD_ID = 67, 379 380Define a ELF build ID for a referenced executable. 381 382 struct build_id_event; /* See above */ 383 384 PERF_RECORD_FINISHED_ROUND = 68, 385 386No event reordering over this header. No payload. 387 388 PERF_RECORD_ID_INDEX = 69, 389 390Map event ids to CPUs and TIDs. 391 392struct id_index_entry { 393 uint64_t id; 394 uint64_t idx; 395 uint64_t cpu; 396 uint64_t tid; 397}; 398 399struct id_index_event { 400 struct perf_event_header header; 401 uint64_t nr; 402 struct id_index_entry entries[nr]; 403}; 404 405 PERF_RECORD_AUXTRACE_INFO = 70, 406 407Auxtrace type specific information. Describe me 408 409struct auxtrace_info_event { 410 struct perf_event_header header; 411 uint32_t type; 412 uint32_t reserved__; /* For alignment */ 413 uint64_t priv[]; 414}; 415 416 PERF_RECORD_AUXTRACE = 71, 417 418Defines auxtrace data. Followed by the actual data. The contents of 419the auxtrace data is dependent on the event and the CPU. For example 420for Intel Processor Trace it contains Processor Trace data generated 421by the CPU. 422 423struct auxtrace_event { 424 struct perf_event_header header; 425 uint64_t size; 426 uint64_t offset; 427 uint64_t reference; 428 uint32_t idx; 429 uint32_t tid; 430 uint32_t cpu; 431 uint32_t reserved__; /* For alignment */ 432}; 433 434struct aux_event { 435 struct perf_event_header header; 436 uint64_t aux_offset; 437 uint64_t aux_size; 438 uint64_t flags; 439}; 440 441 PERF_RECORD_AUXTRACE_ERROR = 72, 442 443Describes an error in hardware tracing 444 445enum auxtrace_error_type { 446 PERF_AUXTRACE_ERROR_ITRACE = 1, 447 PERF_AUXTRACE_ERROR_MAX 448}; 449 450#define MAX_AUXTRACE_ERROR_MSG 64 451 452struct auxtrace_error_event { 453 struct perf_event_header header; 454 uint32_t type; 455 uint32_t code; 456 uint32_t cpu; 457 uint32_t pid; 458 uint32_t tid; 459 uint32_t reserved__; /* For alignment */ 460 uint64_t ip; 461 char msg[MAX_AUXTRACE_ERROR_MSG]; 462}; 463 464 PERF_RECORD_HEADER_FEATURE = 80, 465 466Describes a header feature. These are records used in pipe-mode that 467contain information that otherwise would be in perf.data file's header. 468 469 PERF_RECORD_COMPRESSED = 81, 470 471struct compressed_event { 472 struct perf_event_header header; 473 char data[]; 474}; 475 476The header is followed by compressed data frame that can be decompressed 477into array of perf trace records. The size of the entire compressed event 478record including the header is limited by the max value of header.size. 479 480Event types 481 482Define the event attributes with their IDs. 483 484An array bound by the perf_file_section size. 485 486 struct { 487 struct perf_event_attr attr; /* Size defined by header.attr_size */ 488 struct perf_file_section ids; 489 } 490 491ids points to a array of uint64_t defining the ids for event attr attr. 492 493Pipe-mode data 494 495Pipe-mode avoid seeks in the file by removing the perf_file_section and flags 496from the struct perf_header. The trimmed header is: 497 498struct perf_pipe_file_header { 499 u64 magic; 500 u64 size; 501}; 502 503The information about attrs, data, and event_types is instead in the 504synthesized events PERF_RECORD_ATTR, PERF_RECORD_HEADER_TRACING_DATA, 505PERF_RECORD_HEADER_EVENT_TYPE, and PERF_RECORD_HEADER_FEATURE 506that are generated by perf record in pipe-mode. 507 508 509References: 510 511include/uapi/linux/perf_event.h 512 513This is the canonical description of the kernel generated perf_events 514and the perf_event_attrs. 515 516perf_events manpage 517 518A manpage describing perf_event and perf_event_attr is here: 519http://web.eece.maine.edu/~vweaver/projects/perf_events/programming.html 520This tends to be slightly behind the kernel include, but has better 521descriptions. An (typically older) version of the man page may be 522included with the standard Linux man pages, available with "man 523perf_events" 524 525pmu-tools 526 527https://github.com/andikleen/pmu-tools/tree/master/parser 528 529A definition of the perf.data format in python "construct" format is available 530in pmu-tools parser. This allows to read perf.data from python and dump it. 531 532quipper 533 534The quipper C++ parser is available at 535http://github.com/google/perf_data_converter/tree/master/src/quipper 536 537