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_COMPRESSED = 27, 276 277struct { 278 u32 version; 279 u32 type; 280 u32 level; 281 u32 ratio; 282 u32 mmap_len; 283}; 284 285Indicates that trace contains records of PERF_RECORD_COMPRESSED type 286that have perf_events records in compressed form. 287 288 other bits are reserved and should ignored for now 289 HEADER_FEAT_BITS = 256, 290 291Attributes 292 293This is an array of perf_event_attrs, each attr_size bytes long, which defines 294each event collected. See perf_event.h or the man page for a detailed 295description. 296 297Data 298 299This section is the bulk of the file. It consist of a stream of perf_events 300describing events. This matches the format generated by the kernel. 301See perf_event.h or the manpage for a detailed description. 302 303Some notes on parsing: 304 305Ordering 306 307The events are not necessarily in time stamp order, as they can be 308collected in parallel on different CPUs. If the events should be 309processed in time order they need to be sorted first. It is possible 310to only do a partial sort using the FINISHED_ROUND event header (see 311below). perf record guarantees that there is no reordering over a 312FINISHED_ROUND. 313 314ID vs IDENTIFIER 315 316When the event stream contains multiple events each event is identified 317by an ID. This can be either through the PERF_SAMPLE_ID or the 318PERF_SAMPLE_IDENTIFIER header. The PERF_SAMPLE_IDENTIFIER header is 319at a fixed offset from the event header, which allows reliable 320parsing of the header. Relying on ID may be ambiguous. 321IDENTIFIER is only supported by newer Linux kernels. 322 323Perf record specific events: 324 325In addition to the kernel generated event types perf record adds its 326own event types (in addition it also synthesizes some kernel events, 327for example MMAP events) 328 329 PERF_RECORD_USER_TYPE_START = 64, 330 PERF_RECORD_HEADER_ATTR = 64, 331 332struct attr_event { 333 struct perf_event_header header; 334 struct perf_event_attr attr; 335 uint64_t id[]; 336}; 337 338 PERF_RECORD_HEADER_EVENT_TYPE = 65, /* deprecated */ 339 340#define MAX_EVENT_NAME 64 341 342struct perf_trace_event_type { 343 uint64_t event_id; 344 char name[MAX_EVENT_NAME]; 345}; 346 347struct event_type_event { 348 struct perf_event_header header; 349 struct perf_trace_event_type event_type; 350}; 351 352 353 PERF_RECORD_HEADER_TRACING_DATA = 66, 354 355Describe me 356 357struct tracing_data_event { 358 struct perf_event_header header; 359 uint32_t size; 360}; 361 362 PERF_RECORD_HEADER_BUILD_ID = 67, 363 364Define a ELF build ID for a referenced executable. 365 366 struct build_id_event; /* See above */ 367 368 PERF_RECORD_FINISHED_ROUND = 68, 369 370No event reordering over this header. No payload. 371 372 PERF_RECORD_ID_INDEX = 69, 373 374Map event ids to CPUs and TIDs. 375 376struct id_index_entry { 377 uint64_t id; 378 uint64_t idx; 379 uint64_t cpu; 380 uint64_t tid; 381}; 382 383struct id_index_event { 384 struct perf_event_header header; 385 uint64_t nr; 386 struct id_index_entry entries[nr]; 387}; 388 389 PERF_RECORD_AUXTRACE_INFO = 70, 390 391Auxtrace type specific information. Describe me 392 393struct auxtrace_info_event { 394 struct perf_event_header header; 395 uint32_t type; 396 uint32_t reserved__; /* For alignment */ 397 uint64_t priv[]; 398}; 399 400 PERF_RECORD_AUXTRACE = 71, 401 402Defines auxtrace data. Followed by the actual data. The contents of 403the auxtrace data is dependent on the event and the CPU. For example 404for Intel Processor Trace it contains Processor Trace data generated 405by the CPU. 406 407struct auxtrace_event { 408 struct perf_event_header header; 409 uint64_t size; 410 uint64_t offset; 411 uint64_t reference; 412 uint32_t idx; 413 uint32_t tid; 414 uint32_t cpu; 415 uint32_t reserved__; /* For alignment */ 416}; 417 418struct aux_event { 419 struct perf_event_header header; 420 uint64_t aux_offset; 421 uint64_t aux_size; 422 uint64_t flags; 423}; 424 425 PERF_RECORD_AUXTRACE_ERROR = 72, 426 427Describes an error in hardware tracing 428 429enum auxtrace_error_type { 430 PERF_AUXTRACE_ERROR_ITRACE = 1, 431 PERF_AUXTRACE_ERROR_MAX 432}; 433 434#define MAX_AUXTRACE_ERROR_MSG 64 435 436struct auxtrace_error_event { 437 struct perf_event_header header; 438 uint32_t type; 439 uint32_t code; 440 uint32_t cpu; 441 uint32_t pid; 442 uint32_t tid; 443 uint32_t reserved__; /* For alignment */ 444 uint64_t ip; 445 char msg[MAX_AUXTRACE_ERROR_MSG]; 446}; 447 448 PERF_RECORD_HEADER_FEATURE = 80, 449 450Describes a header feature. These are records used in pipe-mode that 451contain information that otherwise would be in perf.data file's header. 452 453 PERF_RECORD_COMPRESSED = 81, 454 455struct compressed_event { 456 struct perf_event_header header; 457 char data[]; 458}; 459 460The header is followed by compressed data frame that can be decompressed 461into array of perf trace records. The size of the entire compressed event 462record including the header is limited by the max value of header.size. 463 464Event types 465 466Define the event attributes with their IDs. 467 468An array bound by the perf_file_section size. 469 470 struct { 471 struct perf_event_attr attr; /* Size defined by header.attr_size */ 472 struct perf_file_section ids; 473 } 474 475ids points to a array of uint64_t defining the ids for event attr attr. 476 477Pipe-mode data 478 479Pipe-mode avoid seeks in the file by removing the perf_file_section and flags 480from the struct perf_header. The trimmed header is: 481 482struct perf_pipe_file_header { 483 u64 magic; 484 u64 size; 485}; 486 487The information about attrs, data, and event_types is instead in the 488synthesized events PERF_RECORD_ATTR, PERF_RECORD_HEADER_TRACING_DATA, 489PERF_RECORD_HEADER_EVENT_TYPE, and PERF_RECORD_HEADER_FEATURE 490that are generated by perf record in pipe-mode. 491 492 493References: 494 495include/uapi/linux/perf_event.h 496 497This is the canonical description of the kernel generated perf_events 498and the perf_event_attrs. 499 500perf_events manpage 501 502A manpage describing perf_event and perf_event_attr is here: 503http://web.eece.maine.edu/~vweaver/projects/perf_events/programming.html 504This tends to be slightly behind the kernel include, but has better 505descriptions. An (typically older) version of the man page may be 506included with the standard Linux man pages, available with "man 507perf_events" 508 509pmu-tools 510 511https://github.com/andikleen/pmu-tools/tree/master/parser 512 513A definition of the perf.data format in python "construct" format is available 514in pmu-tools parser. This allows to read perf.data from python and dump it. 515 516quipper 517 518The quipper C++ parser is available at 519http://github.com/google/perf_data_converter/tree/master/src/quipper 520 521