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 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 bpf_prog_info_linear, which contains detailed information about
350a BPF program, including type, id, tag, jited/xlated instructions, etc.
351
352        HEADER_BPF_BTF = 26,
353
354Contains BPF Type Format (BTF). For more information about BTF, please
355refer to Documentation/bpf/btf.rst.
356
357struct {
358	u32	id;
359	u32	data_size;
360	char	data[];
361};
362
363        HEADER_COMPRESSED = 27,
364
365struct {
366	u32	version;
367	u32	type;
368	u32	level;
369	u32	ratio;
370	u32	mmap_len;
371};
372
373Indicates that trace contains records of PERF_RECORD_COMPRESSED type
374that have perf_events records in compressed form.
375
376	HEADER_CPU_PMU_CAPS = 28,
377
378	A list of cpu PMU capabilities. The format of data is as below.
379
380struct {
381	u32 nr_cpu_pmu_caps;
382	{
383		char	name[];
384		char	value[];
385	} [nr_cpu_pmu_caps]
386};
387
388
389Example:
390 cpu pmu capabilities: branches=32, max_precise=3, pmu_name=icelake
391
392	HEADER_CLOCK_DATA = 29,
393
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.
397
398struct {
399	u32 version;  /* version = 1 */
400	u32 clockid;
401	u64 wall_clock_ns;
402	u64 clockid_time_ns;
403};
404
405	other bits are reserved and should ignored for now
406	HEADER_FEAT_BITS	= 256,
407
408Attributes
409
410This is an array of perf_event_attrs, each attr_size bytes long, which defines
411each event collected. See perf_event.h or the man page for a detailed
412description.
413
414Data
415
416This section is the bulk of the file. It consist of a stream of perf_events
417describing events. This matches the format generated by the kernel.
418See perf_event.h or the manpage for a detailed description.
419
420Some notes on parsing:
421
422Ordering
423
424The events are not necessarily in time stamp order, as they can be
425collected in parallel on different CPUs. If the events should be
426processed in time order they need to be sorted first. It is possible
427to only do a partial sort using the FINISHED_ROUND event header (see
428below). perf record guarantees that there is no reordering over a
429FINISHED_ROUND.
430
431ID vs IDENTIFIER
432
433When the event stream contains multiple events each event is identified
434by an ID. This can be either through the PERF_SAMPLE_ID or the
435PERF_SAMPLE_IDENTIFIER header. The PERF_SAMPLE_IDENTIFIER header is
436at a fixed offset from the event header, which allows reliable
437parsing of the header. Relying on ID may be ambiguous.
438IDENTIFIER is only supported by newer Linux kernels.
439
440Perf record specific events:
441
442In addition to the kernel generated event types perf record adds its
443own event types (in addition it also synthesizes some kernel events,
444for example MMAP events)
445
446	PERF_RECORD_USER_TYPE_START		= 64,
447	PERF_RECORD_HEADER_ATTR			= 64,
448
449struct attr_event {
450	struct perf_event_header header;
451	struct perf_event_attr attr;
452	uint64_t id[];
453};
454
455	PERF_RECORD_HEADER_EVENT_TYPE		= 65, /* deprecated */
456
457#define MAX_EVENT_NAME 64
458
459struct perf_trace_event_type {
460	uint64_t	event_id;
461	char	name[MAX_EVENT_NAME];
462};
463
464struct event_type_event {
465	struct perf_event_header header;
466	struct perf_trace_event_type event_type;
467};
468
469
470	PERF_RECORD_HEADER_TRACING_DATA		= 66,
471
472Describe me
473
474struct tracing_data_event {
475	struct perf_event_header header;
476	uint32_t size;
477};
478
479	PERF_RECORD_HEADER_BUILD_ID		= 67,
480
481Define a ELF build ID for a referenced executable.
482
483       struct build_id_event;   /* See above */
484
485	PERF_RECORD_FINISHED_ROUND		= 68,
486
487No event reordering over this header. No payload.
488
489	PERF_RECORD_ID_INDEX			= 69,
490
491Map event ids to CPUs and TIDs.
492
493struct id_index_entry {
494	uint64_t id;
495	uint64_t idx;
496	uint64_t cpu;
497	uint64_t tid;
498};
499
500struct id_index_event {
501	struct perf_event_header header;
502	uint64_t nr;
503	struct id_index_entry entries[nr];
504};
505
506	PERF_RECORD_AUXTRACE_INFO		= 70,
507
508Auxtrace type specific information. Describe me
509
510struct auxtrace_info_event {
511	struct perf_event_header header;
512	uint32_t type;
513	uint32_t reserved__; /* For alignment */
514	uint64_t priv[];
515};
516
517	PERF_RECORD_AUXTRACE			= 71,
518
519Defines auxtrace data. Followed by the actual data. The contents of
520the auxtrace data is dependent on the event and the CPU. For example
521for Intel Processor Trace it contains Processor Trace data generated
522by the CPU.
523
524struct auxtrace_event {
525	struct perf_event_header header;
526	uint64_t size;
527	uint64_t offset;
528	uint64_t reference;
529	uint32_t idx;
530	uint32_t tid;
531	uint32_t cpu;
532	uint32_t reserved__; /* For alignment */
533};
534
535struct aux_event {
536	struct perf_event_header header;
537	uint64_t	aux_offset;
538	uint64_t	aux_size;
539	uint64_t	flags;
540};
541
542	PERF_RECORD_AUXTRACE_ERROR		= 72,
543
544Describes an error in hardware tracing
545
546enum auxtrace_error_type {
547	PERF_AUXTRACE_ERROR_ITRACE  = 1,
548	PERF_AUXTRACE_ERROR_MAX
549};
550
551#define MAX_AUXTRACE_ERROR_MSG 64
552
553struct auxtrace_error_event {
554	struct perf_event_header header;
555	uint32_t type;
556	uint32_t code;
557	uint32_t cpu;
558	uint32_t pid;
559	uint32_t tid;
560	uint32_t reserved__; /* For alignment */
561	uint64_t ip;
562	char msg[MAX_AUXTRACE_ERROR_MSG];
563};
564
565	PERF_RECORD_HEADER_FEATURE		= 80,
566
567Describes a header feature. These are records used in pipe-mode that
568contain information that otherwise would be in perf.data file's header.
569
570	PERF_RECORD_COMPRESSED 			= 81,
571
572struct compressed_event {
573	struct perf_event_header	header;
574	char				data[];
575};
576
577The header is followed by compressed data frame that can be decompressed
578into array of perf trace records. The size of the entire compressed event
579record including the header is limited by the max value of header.size.
580
581Event types
582
583Define the event attributes with their IDs.
584
585An array bound by the perf_file_section size.
586
587	struct {
588		struct perf_event_attr attr;   /* Size defined by header.attr_size */
589		struct perf_file_section ids;
590	}
591
592ids points to a array of uint64_t defining the ids for event attr attr.
593
594Pipe-mode data
595
596Pipe-mode avoid seeks in the file by removing the perf_file_section and flags
597from the struct perf_header. The trimmed header is:
598
599struct perf_pipe_file_header {
600	u64				magic;
601	u64				size;
602};
603
604The information about attrs, data, and event_types is instead in the
605synthesized events PERF_RECORD_ATTR, PERF_RECORD_HEADER_TRACING_DATA,
606PERF_RECORD_HEADER_EVENT_TYPE, and PERF_RECORD_HEADER_FEATURE
607that are generated by perf record in pipe-mode.
608
609
610References:
611
612include/uapi/linux/perf_event.h
613
614This is the canonical description of the kernel generated perf_events
615and the perf_event_attrs.
616
617perf_events manpage
618
619A manpage describing perf_event and perf_event_attr is here:
620http://web.eece.maine.edu/~vweaver/projects/perf_events/programming.html
621This tends to be slightly behind the kernel include, but has better
622descriptions.  An (typically older) version of the man page may be
623included with the standard Linux man pages, available with "man
624perf_events"
625
626pmu-tools
627
628https://github.com/andikleen/pmu-tools/tree/master/parser
629
630A definition of the perf.data format in python "construct" format is available
631in pmu-tools parser. This allows to read perf.data from python and dump it.
632
633quipper
634
635The quipper C++ parser is available at
636http://github.com/google/perf_data_converter/tree/master/src/quipper
637
638