5 This document describes the on-disk perf.data format, generated by perf record
6 or perf inject and consumed by the other perf tools.
8 On a high level perf.data contains the events generated by the PMUs, plus metadata.
10 All fields are in native-endian of the machine that generated the perf.data.
12 When perf is writing to a pipe it uses a special version of the file
13 format that does not rely on seeking to adjust data offsets. This
14 format is described in "Pipe-mode data" section. The pipe data version can be
15 augmented with additional events using perf inject.
17 The file starts with a 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;
30 The magic number identifies the perf file and the version. Current perf versions
31 use PERFILE2. Old perf versions generated a version 1 format (PERFFILE). Version 1
32 is not described here. The magic number also identifies the endian. When the
33 magic value is 64bit byte swapped compared the file is in non-native
36 A perf_file_section contains a pointer to another section of the perf file.
37 The header contains three such pointers: for attributes, data and event types.
39 struct perf_file_section {
40 uint64_t offset; /* offset from start of file */
41 uint64_t size; /* size of the section */
46 For each of the optional features a perf_file_section it placed after the data
47 section if the feature bit is set in the perf_header flags bitset. The
48 respective perf_file_section points to the data of the additional header and
51 Some headers consist of strings, which are defined like this:
53 struct perf_header_string {
55 char string[len]; /* zero terminated */
58 Some headers consist of a sequence of strings, which start with a
60 struct perf_header_string_list {
62 struct perf_header_string strings[nr]; /* variable length records */
65 The bits are the flags bits in a 256 bit bitmap starting with
66 flags. These define the valid bits:
68 HEADER_RESERVED = 0, /* always cleared */
69 HEADER_FIRST_FEATURE = 1,
70 HEADER_TRACING_DATA = 1,
76 The header consists of an sequence of build_id_event. The size of each record
77 is defined by header.size (see perf_event.h). Each event defines a ELF build id
78 for a executable file name for a pid. An ELF build id is a unique identifier
79 assigned by the linker to an executable.
81 struct build_id_event {
82 struct perf_event_header header;
85 char filename[header.size - offsetof(struct build_id_event, filename)];
90 A perf_header_string with the hostname where the data was collected
95 A perf_header_string with the os release where the data was collected
100 A perf_header_string with the perf user tool version where the
101 data was collected. This is the same as the version of the source tree
102 the perf tool was built from.
106 A perf_header_string with the CPU architecture (uname -m)
110 A structure defining the number of CPUs.
113 uint32_t nr_cpus_available; /* CPUs not yet onlined */
114 uint32_t nr_cpus_online;
119 A perf_header_string with description of the CPU. On x86 this is the model name
124 A perf_header_string with the exact CPU type. On x86 this is
125 vendor,family,model,stepping. For example: GenuineIntel,6,69,1
127 HEADER_TOTAL_MEM = 10,
129 An uint64_t with the total memory in kilobytes.
133 A perf_header_string_list with the perf arg-vector used to collect the data.
135 HEADER_EVENT_DESC = 12,
137 Another description of the perf_event_attrs, more detailed than header.attrs
138 including IDs and names. See perf_event.h or the man page for a description
139 of a struct perf_event_attr.
142 uint32_t nr; /* number of events */
143 uint32_t attr_size; /* size of each perf_event_attr */
145 struct perf_event_attr attr; /* size of attr_size */
147 struct perf_header_string event_string;
148 uint64_t ids[nr_ids];
149 } events[nr]; /* Variable length records */
152 HEADER_CPU_TOPOLOGY = 13,
156 * First revision of HEADER_CPU_TOPOLOGY
158 * See 'struct perf_header_string_list' definition earlier
162 struct perf_header_string_list cores; /* Variable length */
163 struct perf_header_string_list threads; /* Variable length */
166 * Second revision of HEADER_CPU_TOPOLOGY, older tools
167 * will not consider what comes next
173 } cpus[nr]; /* Variable length records */
174 /* 'nr' comes from previously processed HEADER_NRCPUS's nr_cpu_avail */
177 * Third revision of HEADER_CPU_TOPOLOGY, older tools
178 * will not consider what comes next
181 struct perf_header_string_list dies; /* Variable length */
182 uint32_t die_id[nr_cpus_avail]; /* from previously processed HEADER_NR_CPUS, VLA */
186 sibling sockets : 0-8
189 sibling threads : 0-1
190 sibling threads : 2-3
191 sibling threads : 4-5
192 sibling threads : 6-7
194 HEADER_NUMA_TOPOLOGY = 14,
196 A list of NUMA node descriptions
204 struct perf_header_string cpus;
205 } nodes[nr]; /* Variable length records */
208 HEADER_BRANCH_STACK = 15,
210 Not implemented in perf.
212 HEADER_PMU_MAPPINGS = 16,
214 A list of PMU structures, defining the different PMUs supported by perf.
220 struct perf_header_string pmu_name;
221 } [nr]; /* Variable length records */
224 HEADER_GROUP_DESC = 17,
226 Description of counter groups ({...} in perf syntax)
231 struct perf_header_string string;
234 } [nr]; /* Variable length records */
237 HEADER_AUXTRACE = 18,
239 Define additional auxtrace areas in the perf.data. auxtrace is used to store
240 undecoded hardware tracing information, such as Intel Processor Trace data.
243 * struct auxtrace_index_entry - indexes a AUX area tracing event within a
245 * @file_offset: offset within the perf.data file
246 * @sz: size of the event
248 struct auxtrace_index_entry {
253 #define PERF_AUXTRACE_INDEX_ENTRY_COUNT 256
256 * struct auxtrace_index - index of AUX area tracing events within a perf.data
258 * @list: linking a number of arrays of entries
259 * @nr: number of entries
260 * @entries: array of entries
262 struct auxtrace_index {
263 struct list_head list;
265 struct auxtrace_index_entry entries[PERF_AUXTRACE_INDEX_ENTRY_COUNT];
270 This is merely a flag signifying that the data section contains data
271 recorded from perf stat record.
275 Description of the cache hierarchy. Based on the Linux sysfs format
276 in /sys/devices/system/cpu/cpu*/cache/
278 u32 version Currently always 1
279 u32 number_of_cache_levels
286 struct perf_header_string type;
287 struct perf_header_string size;
288 struct perf_header_string map;
289 }[number_of_cache_levels];
291 HEADER_SAMPLE_TIME = 21,
293 Two uint64_t for the time of first sample and the time of last sample.
295 HEADER_SAMPLE_TOPOLOGY = 22,
297 Physical memory map and its node assignments.
299 The format of data in MEM_TOPOLOGY is as follows:
301 u64 version; // Currently 1
302 u64 block_size_bytes; // /sys/devices/system/memory/block_size_bytes
303 u64 count; // number of nodes
306 u64 node_id; // node index
307 u64 size; // size of bitmap
309 /* size of bitmap again */
311 /* bitmap of memory indexes that belongs to node */
312 /* /sys/devices/system/node/node<NODE>/memory<INDEX> */
313 u64 entries[(bitmapsize/64)+1];
317 The MEM_TOPOLOGY can be displayed with following command:
319 $ perf report --header-only -I
321 # memory nodes (nr 1, block size 0x8000000):
326 One uint64_t for the clockid frequency, specified, for instance, via 'perf
327 record -k' (see clock_gettime()), to enable timestamps derived metrics
328 conversion into wall clock time on the reporting stage.
330 HEADER_DIR_FORMAT = 24,
332 The data files layout is described by HEADER_DIR_FORMAT feature. Currently it
333 holds only version number (1):
337 The current version holds only version value (1) means that data files:
339 - Follow the 'data.*' name format.
341 - Contain raw events data in standard perf format as read from kernel (and need
344 Future versions are expected to describe different data files layout according
347 HEADER_BPF_PROG_INFO = 25,
349 struct bpf_prog_info_linear, which contains detailed information about
350 a BPF program, including type, id, tag, jited/xlated instructions, etc.
354 Contains BPF Type Format (BTF). For more information about BTF, please
355 refer to Documentation/bpf/btf.rst.
363 HEADER_COMPRESSED = 27,
373 Indicates that trace contains records of PERF_RECORD_COMPRESSED type
374 that have perf_events records in compressed form.
376 HEADER_CPU_PMU_CAPS = 28,
378 A list of cpu PMU capabilities. The format of data is as below.
390 cpu pmu capabilities: branches=32, max_precise=3, pmu_name=icelake
392 HEADER_CLOCK_DATA = 29,
394 Contains clock id and its reference time together with wall clock
395 time taken at the 'same time', both values are in nanoseconds.
396 The format of data is as below.
399 u32 version; /* version = 1 */
405 HEADER_HYBRID_TOPOLOGY = 30,
407 Indicate the hybrid CPUs. The format of data is as below.
414 } [nr]; /* Variable length records */
419 cpu_core cpu list : 0-15
420 cpu_atom cpu list : 16-23
422 HEADER_HYBRID_CPU_PMU_CAPS = 31,
424 A list of hybrid CPU PMU capabilities.
438 other bits are reserved and should ignored for now
439 HEADER_FEAT_BITS = 256,
443 This is an array of perf_event_attrs, each attr_size bytes long, which defines
444 each event collected. See perf_event.h or the man page for a detailed
449 This section is the bulk of the file. It consist of a stream of perf_events
450 describing events. This matches the format generated by the kernel.
451 See perf_event.h or the manpage for a detailed description.
453 Some notes on parsing:
457 The events are not necessarily in time stamp order, as they can be
458 collected in parallel on different CPUs. If the events should be
459 processed in time order they need to be sorted first. It is possible
460 to only do a partial sort using the FINISHED_ROUND event header (see
461 below). perf record guarantees that there is no reordering over a
466 When the event stream contains multiple events each event is identified
467 by an ID. This can be either through the PERF_SAMPLE_ID or the
468 PERF_SAMPLE_IDENTIFIER header. The PERF_SAMPLE_IDENTIFIER header is
469 at a fixed offset from the event header, which allows reliable
470 parsing of the header. Relying on ID may be ambiguous.
471 IDENTIFIER is only supported by newer Linux kernels.
473 Perf record specific events:
475 In addition to the kernel generated event types perf record adds its
476 own event types (in addition it also synthesizes some kernel events,
477 for example MMAP events)
479 PERF_RECORD_USER_TYPE_START = 64,
480 PERF_RECORD_HEADER_ATTR = 64,
483 struct perf_event_header header;
484 struct perf_event_attr attr;
488 PERF_RECORD_HEADER_EVENT_TYPE = 65, /* deprecated */
490 #define MAX_EVENT_NAME 64
492 struct perf_trace_event_type {
494 char name[MAX_EVENT_NAME];
497 struct event_type_event {
498 struct perf_event_header header;
499 struct perf_trace_event_type event_type;
503 PERF_RECORD_HEADER_TRACING_DATA = 66,
507 struct tracing_data_event {
508 struct perf_event_header header;
512 PERF_RECORD_HEADER_BUILD_ID = 67,
514 Define a ELF build ID for a referenced executable.
516 struct build_id_event; /* See above */
518 PERF_RECORD_FINISHED_ROUND = 68,
520 No event reordering over this header. No payload.
522 PERF_RECORD_ID_INDEX = 69,
524 Map event ids to CPUs and TIDs.
526 struct id_index_entry {
533 struct id_index_event {
534 struct perf_event_header header;
536 struct id_index_entry entries[nr];
539 PERF_RECORD_AUXTRACE_INFO = 70,
541 Auxtrace type specific information. Describe me
543 struct auxtrace_info_event {
544 struct perf_event_header header;
546 uint32_t reserved__; /* For alignment */
550 PERF_RECORD_AUXTRACE = 71,
552 Defines auxtrace data. Followed by the actual data. The contents of
553 the auxtrace data is dependent on the event and the CPU. For example
554 for Intel Processor Trace it contains Processor Trace data generated
557 struct auxtrace_event {
558 struct perf_event_header header;
565 uint32_t reserved__; /* For alignment */
569 struct perf_event_header header;
575 PERF_RECORD_AUXTRACE_ERROR = 72,
577 Describes an error in hardware tracing
579 enum auxtrace_error_type {
580 PERF_AUXTRACE_ERROR_ITRACE = 1,
581 PERF_AUXTRACE_ERROR_MAX
584 #define MAX_AUXTRACE_ERROR_MSG 64
586 struct auxtrace_error_event {
587 struct perf_event_header header;
593 uint32_t reserved__; /* For alignment */
595 char msg[MAX_AUXTRACE_ERROR_MSG];
598 PERF_RECORD_HEADER_FEATURE = 80,
600 Describes a header feature. These are records used in pipe-mode that
601 contain information that otherwise would be in perf.data file's header.
603 PERF_RECORD_COMPRESSED = 81,
605 struct compressed_event {
606 struct perf_event_header header;
610 The header is followed by compressed data frame that can be decompressed
611 into array of perf trace records. The size of the entire compressed event
612 record including the header is limited by the max value of header.size.
616 Define the event attributes with their IDs.
618 An array bound by the perf_file_section size.
621 struct perf_event_attr attr; /* Size defined by header.attr_size */
622 struct perf_file_section ids;
625 ids points to a array of uint64_t defining the ids for event attr attr.
629 Pipe-mode avoid seeks in the file by removing the perf_file_section and flags
630 from the struct perf_header. The trimmed header is:
632 struct perf_pipe_file_header {
637 The information about attrs, data, and event_types is instead in the
638 synthesized events PERF_RECORD_ATTR, PERF_RECORD_HEADER_TRACING_DATA,
639 PERF_RECORD_HEADER_EVENT_TYPE, and PERF_RECORD_HEADER_FEATURE
640 that are generated by perf record in pipe-mode.
645 include/uapi/linux/perf_event.h
647 This is the canonical description of the kernel generated perf_events
648 and the perf_event_attrs.
652 A manpage describing perf_event and perf_event_attr is here:
653 http://web.eece.maine.edu/~vweaver/projects/perf_events/programming.html
654 This tends to be slightly behind the kernel include, but has better
655 descriptions. An (typically older) version of the man page may be
656 included with the standard Linux man pages, available with "man
661 https://github.com/andikleen/pmu-tools/tree/master/parser
663 A definition of the perf.data format in python "construct" format is available
664 in pmu-tools parser. This allows to read perf.data from python and dump it.
668 The quipper C++ parser is available at
669 http://github.com/google/perf_data_converter/tree/master/src/quipper