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