1 perf.data format
2
3 Uptodate as of v4.7
4
5 This document describes the on-disk perf.data
6 or perf inject and consumed by the other perf
7
8 On a high level perf.data contains the events
9
10 All fields are in native-endian of the machine
11
12 When perf is writing to a pipe it uses a speci
13 format that does not rely on seeking to adjust
14 format is described in "Pipe-mode data" sectio
15 augmented with additional events using perf in
16
17 The file starts with a perf_header:
18
19 struct perf_header {
20 char magic[8]; /* PERFILE2 */
21 uint64_t size; /* size of the
22 uint64_t attr_size; /* size of an
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
30 The magic number identifies the perf file and
31 use PERFILE2. Old perf versions generated a ve
32 is not described here. The magic number also i
33 magic value is 64bit byte swapped compared the
34 endian.
35
36 A perf_file_section contains a pointer to anot
37 The header contains three such pointers: for a
38
39 struct perf_file_section {
40 uint64_t offset; /* offset from
41 uint64_t size; /* size of the
42 };
43
44 Flags section:
45
46 For each of the optional features a perf_file_
47 section if the feature bit is set in the perf_
48 respective perf_file_section points to the dat
49 defines its size.
50
51 Some headers consist of strings, which are def
52
53 struct perf_header_string {
54 uint32_t len;
55 char string[len]; /* zero terminated */
56 };
57
58 Some headers consist of a sequence of strings,
59
60 struct perf_header_string_list {
61 uint32_t nr;
62 struct perf_header_string strings[nr]; /*
63 };
64
65 The bits are the flags bits in a 256 bit bitma
66 flags. These define the valid bits:
67
68 HEADER_RESERVED = 0, /* alw
69 HEADER_FIRST_FEATURE = 1,
70 HEADER_TRACING_DATA = 1,
71
72 Describe me.
73
74 HEADER_BUILD_ID = 2,
75
76 The header consists of an sequence of build_id
77 is defined by header.size (see perf_event.h).
78 for a executable file name for a pid. An ELF b
79 assigned by the linker to an executable.
80
81 struct build_id_event {
82 struct perf_event_header header;
83 pid_t pid;
84 uint8_t build_id[24];
85 char filename[head
86 };
87
88 HEADER_HOSTNAME = 3,
89
90 A perf_header_string with the hostname where t
91 (uname -n)
92
93 HEADER_OSRELEASE = 4,
94
95 A perf_header_string with the os release where
96 (uname -r)
97
98 HEADER_VERSION = 5,
99
100 A perf_header_string with the perf user tool v
101 data was collected. This is the same as the ve
102 the perf tool was built from.
103
104 HEADER_ARCH = 6,
105
106 A perf_header_string with the CPU architecture
107
108 HEADER_NRCPUS = 7,
109
110 A structure defining the number of CPUs.
111
112 struct nr_cpus {
113 uint32_t nr_cpus_available; /* CPUs not
114 uint32_t nr_cpus_online;
115 };
116
117 HEADER_CPUDESC = 8,
118
119 A perf_header_string with description of the C
120 in /proc/cpuinfo
121
122 HEADER_CPUID = 9,
123
124 A perf_header_string with the exact CPU type.
125 vendor,family,model,stepping. For example: Gen
126
127 HEADER_TOTAL_MEM = 10,
128
129 An uint64_t with the total memory in kilobytes
130
131 HEADER_CMDLINE = 11,
132
133 A perf_header_string_list with the perf arg-ve
134
135 HEADER_EVENT_DESC = 12,
136
137 Another description of the perf_event_attrs, m
138 including IDs and names. See perf_event.h or t
139 of a struct perf_event_attr.
140
141 struct {
142 uint32_t nr; /* number of events */
143 uint32_t attr_size; /* size of each per
144 struct {
145 struct perf_event_attr attr; /*
146 uint32_t nr_ids;
147 struct perf_header_string event_
148 uint64_t ids[nr_ids];
149 } events[nr]; /* Variable length record
150 };
151
152 HEADER_CPU_TOPOLOGY = 13,
153
154 struct {
155 /*
156 * First revision of HEADER_CPU_TOPOLO
157 *
158 * See 'struct perf_header_string_list
159 * in this file.
160 */
161
162 struct perf_header_string_list cores; /
163 struct perf_header_string_list threads;
164
165 /*
166 * Second revision of HEADER_CPU_TOPOLO
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
175
176 /*
177 * Third revision of HEADER_CPU_TOPOLO
178 * will not consider what comes next
179 */
180
181 struct perf_header_string_list dies; /
182 uint32_t die_id[nr_cpus_avail]; /* fro
183 };
184
185 Example:
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
198 struct {
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
210 Not implemented in perf.
211
212 HEADER_PMU_MAPPINGS = 16,
213
214 A list of PMU structures, defining the
215
216 struct {
217 uint32_t nr;
218 struct pmu {
219 uint32_t pmu_type;
220 struct perf_header_string pmu_na
221 } [nr]; /* Variable length records */
222 };
223
224 HEADER_GROUP_DESC = 17,
225
226 Description of counter groups ({...} i
227
228 struct {
229 uint32_t nr;
230 struct {
231 struct perf_header_string stri
232 uint32_t leader_idx;
233 uint32_t nr_members;
234 } [nr]; /* Variable length records */
235 };
236
237 HEADER_AUXTRACE = 18,
238
239 Define additional auxtrace areas in the perf.d
240 undecoded hardware tracing information, such a
241
242 /**
243 * struct auxtrace_index_entry - indexes a AUX
244 * perf.data fil
245 * @file_offset: offset within the perf.data f
246 * @sz: size of the event
247 */
248 struct 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 t
257 * file.
258 * @list: linking a number of arrays of entrie
259 * @nr: number of entries
260 * @entries: array of entries
261 */
262 struct auxtrace_index {
263 struct list_head list;
264 size_t nr;
265 struct auxtrace_index_entry entries[PE
266 };
267
268 HEADER_STAT = 19,
269
270 This is merely a flag signifying that the data
271 recorded from perf stat record.
272
273 HEADER_CACHE = 20,
274
275 Description of the cache hierarchy. Based on t
276 in /sys/devices/system/cpu/cpu*/cache/
277
278 u32 version Currently always 1
279 u32 number_of_cache_levels
280
281 struct {
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
293 Two uint64_t for the time of first sample and
294
295 HEADER_SAMPLE_TOPOLOGY = 22,
296
297 Physical memory map and its node assignments.
298
299 The format of data in MEM_TOPOLOGY is as follo
300
301 u64 version; // Currently 1
302 u64 block_size_bytes; // /sys/device
303 u64 count; // number of n
304
305 struct memory_node {
306 u64 node_id; // node index
307 u64 size; // size of bit
308 struct bitmap {
309 /* size of bitmap again */
310 u64 bitmapsize;
311 /* bitmap of memory indexes th
312 /* /sys/devices/system/node/no
313 u64 entries[(bitmapsize/64)+1]
314 }
315 }[count];
316
317 The MEM_TOPOLOGY can be displayed with followi
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
326 One uint64_t for the clockid frequency, specif
327 record -k' (see clock_gettime()), to enable ti
328 conversion into wall clock time on the reporti
329
330 HEADER_DIR_FORMAT = 24,
331
332 The data files layout is described by HEADER_D
333 holds only version number (1):
334
335 uint64_t version;
336
337 The current version holds only version value (
338
339 - Follow the 'data.*' name format.
340
341 - Contain raw events data in standard perf for
342 to be sorted)
343
344 Future versions are expected to describe diffe
345 to special needs.
346
347 HEADER_BPF_PROG_INFO = 25,
348
349 struct perf_bpil, which contains detailed info
350 a BPF program, including type, id, tag, jited/
351
352 HEADER_BPF_BTF = 26,
353
354 Contains BPF Type Format (BTF). For more infor
355 refer to Documentation/bpf/btf.rst.
356
357 struct {
358 u32 id;
359 u32 data_size;
360 char data[];
361 };
362
363 HEADER_COMPRESSED = 27,
364
365 struct {
366 u32 version;
367 u32 type;
368 u32 level;
369 u32 ratio;
370 u32 mmap_len;
371 };
372
373 Indicates that trace contains records of PERF_
374 that have perf_events records in compressed fo
375
376 HEADER_CPU_PMU_CAPS = 28,
377
378 A list of cpu PMU capabilities. The fo
379
380 struct {
381 u32 nr_cpu_pmu_caps;
382 {
383 char name[];
384 char value[];
385 } [nr_cpu_pmu_caps]
386 };
387
388
389 Example:
390 cpu pmu capabilities: branches=32, max_precis
391
392 HEADER_CLOCK_DATA = 29,
393
394 Contains clock id and its reference ti
395 time taken at the 'same time', both va
396 The format of data is as below.
397
398 struct {
399 u32 version; /* version = 1 */
400 u32 clockid;
401 u64 wall_clock_ns;
402 u64 clockid_time_ns;
403 };
404
405 HEADER_HYBRID_TOPOLOGY = 30,
406
407 Indicate the hybrid CPUs. The format of data i
408
409 struct {
410 u32 nr;
411 struct {
412 char pmu_name[];
413 char cpus[];
414 } [nr]; /* Variable length records */
415 };
416
417 Example:
418 hybrid cpu system:
419 cpu_core cpu list : 0-15
420 cpu_atom cpu list : 16-23
421
422 HEADER_PMU_CAPS = 31,
423
424 List of pmu capabilities (except cpu p
425 covered by HEADER_CPU_PMU_CAPS). Note
426 capabilities are also stored here.
427
428 struct {
429 u32 nr_pmu;
430 struct {
431 u32 nr_caps;
432 {
433 char name[];
434 char value[];
435 } [nr_caps];
436 char pmu_name[];
437 } [nr_pmu];
438 };
439
440 other bits are reserved and should ign
441 HEADER_FEAT_BITS = 256,
442
443 Attributes
444
445 This is an array of perf_event_attrs, each att
446 each event collected. See perf_event.h or the
447 description.
448
449 Data
450
451 This section is the bulk of the file. It consi
452 describing events. This matches the format gen
453 See perf_event.h or the manpage for a detailed
454
455 Some notes on parsing:
456
457 Ordering
458
459 The events are not necessarily in time stamp o
460 collected in parallel on different CPUs. If th
461 processed in time order they need to be sorted
462 to only do a partial sort using the FINISHED_R
463 below). perf record guarantees that there is n
464 FINISHED_ROUND.
465
466 ID vs IDENTIFIER
467
468 When the event stream contains multiple events
469 by an ID. This can be either through the PERF_
470 PERF_SAMPLE_IDENTIFIER header. The PERF_SAMPLE
471 at a fixed offset from the event header, which
472 parsing of the header. Relying on ID may be am
473 IDENTIFIER is only supported by newer Linux ke
474
475 Perf record specific events:
476
477 In addition to the kernel generated event type
478 own event types (in addition it also synthesiz
479 for example MMAP events)
480
481 PERF_RECORD_USER_TYPE_START
482 PERF_RECORD_HEADER_ATTR
483
484 struct attr_event {
485 struct perf_event_header header;
486 struct perf_event_attr attr;
487 uint64_t id[];
488 };
489
490 PERF_RECORD_HEADER_EVENT_TYPE
491
492 #define MAX_EVENT_NAME 64
493
494 struct perf_trace_event_type {
495 uint64_t event_id;
496 char name[MAX_EVENT_NAME];
497 };
498
499 struct event_type_event {
500 struct perf_event_header header;
501 struct perf_trace_event_type event_typ
502 };
503
504
505 PERF_RECORD_HEADER_TRACING_DATA
506
507 Describe me
508
509 struct tracing_data_event {
510 struct perf_event_header header;
511 uint32_t size;
512 };
513
514 PERF_RECORD_HEADER_BUILD_ID
515
516 Define a ELF build ID for a referenced executa
517
518 struct build_id_event; /* See above *
519
520 PERF_RECORD_FINISHED_ROUND
521
522 No event reordering over this header. No paylo
523
524 PERF_RECORD_ID_INDEX
525
526 Map event ids to CPUs and TIDs.
527
528 struct id_index_entry {
529 uint64_t id;
530 uint64_t idx;
531 uint64_t cpu;
532 uint64_t tid;
533 };
534
535 struct id_index_event {
536 struct perf_event_header header;
537 uint64_t nr;
538 struct id_index_entry entries[nr];
539 };
540
541 PERF_RECORD_AUXTRACE_INFO
542
543 Auxtrace type specific information. Describe m
544
545 struct auxtrace_info_event {
546 struct perf_event_header header;
547 uint32_t type;
548 uint32_t reserved__; /* For alignment
549 uint64_t priv[];
550 };
551
552 PERF_RECORD_AUXTRACE
553
554 Defines auxtrace data. Followed by the actual
555 the auxtrace data is dependent on the event an
556 for Intel Processor Trace it contains Processo
557 by the CPU.
558
559 struct auxtrace_event {
560 struct perf_event_header header;
561 uint64_t size;
562 uint64_t offset;
563 uint64_t reference;
564 uint32_t idx;
565 uint32_t tid;
566 uint32_t cpu;
567 uint32_t reserved__; /* For alignment
568 };
569
570 struct aux_event {
571 struct perf_event_header header;
572 uint64_t aux_offset;
573 uint64_t aux_size;
574 uint64_t flags;
575 };
576
577 PERF_RECORD_AUXTRACE_ERROR
578
579 Describes an error in hardware tracing
580
581 enum auxtrace_error_type {
582 PERF_AUXTRACE_ERROR_ITRACE = 1,
583 PERF_AUXTRACE_ERROR_MAX
584 };
585
586 #define MAX_AUXTRACE_ERROR_MSG 64
587
588 struct auxtrace_error_event {
589 struct perf_event_header header;
590 uint32_t type;
591 uint32_t code;
592 uint32_t cpu;
593 uint32_t pid;
594 uint32_t tid;
595 uint32_t reserved__; /* For alignment
596 uint64_t ip;
597 char msg[MAX_AUXTRACE_ERROR_MSG];
598 };
599
600 PERF_RECORD_HEADER_FEATURE
601
602 Describes a header feature. These are records
603 contain information that otherwise would be in
604
605 PERF_RECORD_COMPRESSED
606
607 struct compressed_event {
608 struct perf_event_header header
609 char data[]
610 };
611
612 PERF_RECORD_FINISHED_INIT
613
614 Marks the end of records for the system, pre-e
615 sessions, etc. Those are the ones prefixed PER
616
617 This is used, for instance, to 'perf inject' e
618 regular events, those emitted by the kernel, t
619 host records.
620
621
622 The header is followed by compressed data fram
623 into array of perf trace records. The size of
624 record including the header is limited by the
625
626 Event types
627
628 Define the event attributes with their IDs.
629
630 An array bound by the perf_file_section size.
631
632 struct {
633 struct perf_event_attr attr;
634 struct perf_file_section ids;
635 }
636
637 ids points to a array of uint64_t defining the
638
639 Pipe-mode data
640
641 Pipe-mode avoid seeks in the file by removing
642 from the struct perf_header. The trimmed heade
643
644 struct perf_pipe_file_header {
645 u64 magic;
646 u64 size;
647 };
648
649 The information about attrs, data, and event_t
650 synthesized events PERF_RECORD_ATTR, PERF_RECO
651 PERF_RECORD_HEADER_EVENT_TYPE, and PERF_RECORD
652 that are generated by perf record in pipe-mode
653
654
655 References:
656
657 include/uapi/linux/perf_event.h
658
659 This is the canonical description of the kerne
660 and the perf_event_attrs.
661
662 perf_events manpage
663
664 A manpage describing perf_event and perf_event
665 http://web.eece.maine.edu/~vweaver/projects/pe
666 This tends to be slightly behind the kernel in
667 descriptions. An (typically older) version of
668 included with the standard Linux man pages, av
669 perf_events"
670
671 pmu-tools
672
673 https://github.com/andikleen/pmu-tools/tree/ma
674
675 A definition of the perf.data format in python
676 in pmu-tools parser. This allows to read perf.
677
678 quipper
679
680 The quipper C++ parser is available at
681 http://github.com/google/perf_data_converter/t
682
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.