tools/perf/Documentation/perf.data-file-format.txt

   1 perf.data format
   2
   3 Uptodate as of v4.7
   4
   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.
   7
   8 On a high level perf.data contains the events generated by the PMUs, plus metadata.
   9
  10 All fields are in native-endian of the machine that generated the perf.data.
  11
  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.
  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 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
  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
  34 endian.
  35
  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.
  38
  39 struct perf_file_section {
  40         uint64_t offset;        /* offset from start of file */
  41         uint64_t size;          /* size of the section */
  42 };
  43
  44 Flags section:
  45
  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
  49 defines its size.
  50
  51 Some headers consist of strings, which are defined like this:
  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, which start with a
  59
  60 struct perf_header_string_list {
  61      uint32_t nr;
  62      struct perf_header_string strings[nr]; /* variable length records */
  63 };
  64
  65 The bits are the flags bits in a 256 bit bitmap starting with
  66 flags. These define the valid bits:
  67
  68         HEADER_RESERVED         = 0,    /* always cleared */
  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_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.
  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[header.size - offsetof(struct build_id_event, filename)];
  86 };
  87
  88         HEADER_HOSTNAME = 3,
  89
  90 A perf_header_string with the hostname where the data was collected
  91 (uname -n)
  92
  93         HEADER_OSRELEASE = 4,
  94
  95 A perf_header_string with the os release where the data was collected
  96 (uname -r)
  97
  98         HEADER_VERSION = 5,
  99
 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.
 103
 104         HEADER_ARCH = 6,
 105
 106 A perf_header_string with the CPU architecture (uname -m)
 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 yet onlined */
 114        uint32_t nr_cpus_online;
 115 };
 116
 117         HEADER_CPUDESC = 8,
 118
 119 A perf_header_string with description of the CPU. On x86 this is the model name
 120 in /proc/cpuinfo
 121
 122         HEADER_CPUID = 9,
 123
 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
 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-vector used to collect the data.
 134
 135         HEADER_EVENT_DESC = 12,
 136
 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.
 140
 141 struct {
 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
 154 struct {
 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
 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 different PMUs supported by perf.
 215
 216 struct {
 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
 228 struct {
 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
 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.
 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  */
 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 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  */
 262 struct 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
 270 This is merely a flag signifying that the data section contains data
 271 recorded from perf stat record.
 272
 273         HEADER_CACHE = 20,
 274
 275 Description of the cache hierarchy. Based on the Linux sysfs format
 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 the time of last sample.
 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 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
 305 struct 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
 317 The 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
 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.
 329
 330         HEADER_DIR_FORMAT = 24,
 331
 332 The data files layout is described by HEADER_DIR_FORMAT feature.  Currently it
 333 holds only version number (1):
 334
 335   uint64_t version;
 336
 337 The 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
 344 Future versions are expected to describe different data files layout according
 345 to special needs.
 346
 347         HEADER_BPF_PROG_INFO = 25,
 348
 349 struct bpf_prog_info_linear, which contains detailed information about
 350 a BPF program, including type, id, tag, jited/xlated instructions, etc.
 351
 352         HEADER_BPF_BTF = 26,
 353
 354 Contains BPF Type Format (BTF). For more information about BTF, please
 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_RECORD_COMPRESSED type
 374 that 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
 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_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
 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 is as below.
 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_HYBRID_CPU_PMU_CAPS = 31,
 423
 424         A list of hybrid CPU PMU capabilities.
 425
 426 struct {
 427         u32 nr_pmu;
 428         struct {
 429                 u32 nr_cpu_pmu_caps;
 430                 {
 431                         char    name[];
 432                         char    value[];
 433                 } [nr_cpu_pmu_caps];
 434                 char pmu_name[];
 435         } [nr_pmu];
 436 };
 437
 438         other bits are reserved and should ignored for now
 439         HEADER_FEAT_BITS        = 256,
 440
 441 Attributes
 442
 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
 445 description.
 446
 447 Data
 448
 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.
 452
 453 Some notes on parsing:
 454
 455 Ordering
 456
 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
 462 FINISHED_ROUND.
 463
 464 ID vs IDENTIFIER
 465
 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.
 472
 473 Perf record specific events:
 474
 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)
 478
 479         PERF_RECORD_USER_TYPE_START             = 64,
 480         PERF_RECORD_HEADER_ATTR                 = 64,
 481
 482 struct attr_event {
 483         struct perf_event_header header;
 484         struct perf_event_attr attr;
 485         uint64_t id[];
 486 };
 487
 488         PERF_RECORD_HEADER_EVENT_TYPE           = 65, /* deprecated */
 489
 490 #define MAX_EVENT_NAME 64
 491
 492 struct perf_trace_event_type {
 493         uint64_t        event_id;
 494         char    name[MAX_EVENT_NAME];
 495 };
 496
 497 struct event_type_event {
 498         struct perf_event_header header;
 499         struct perf_trace_event_type event_type;
 500 };
 501
 502
 503         PERF_RECORD_HEADER_TRACING_DATA         = 66,
 504
 505 Describe me
 506
 507 struct tracing_data_event {
 508         struct perf_event_header header;
 509         uint32_t size;
 510 };
 511
 512         PERF_RECORD_HEADER_BUILD_ID             = 67,
 513
 514 Define a ELF build ID for a referenced executable.
 515
 516        struct build_id_event;   /* See above */
 517
 518         PERF_RECORD_FINISHED_ROUND              = 68,
 519
 520 No event reordering over this header. No payload.
 521
 522         PERF_RECORD_ID_INDEX                    = 69,
 523
 524 Map event ids to CPUs and TIDs.
 525
 526 struct id_index_entry {
 527         uint64_t id;
 528         uint64_t idx;
 529         uint64_t cpu;
 530         uint64_t tid;
 531 };
 532
 533 struct id_index_event {
 534         struct perf_event_header header;
 535         uint64_t nr;
 536         struct id_index_entry entries[nr];
 537 };
 538
 539         PERF_RECORD_AUXTRACE_INFO               = 70,
 540
 541 Auxtrace type specific information. Describe me
 542
 543 struct auxtrace_info_event {
 544         struct perf_event_header header;
 545         uint32_t type;
 546         uint32_t reserved__; /* For alignment */
 547         uint64_t priv[];
 548 };
 549
 550         PERF_RECORD_AUXTRACE                    = 71,
 551
 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
 555 by the CPU.
 556
 557 struct auxtrace_event {
 558         struct perf_event_header header;
 559         uint64_t size;
 560         uint64_t offset;
 561         uint64_t reference;
 562         uint32_t idx;
 563         uint32_t tid;
 564         uint32_t cpu;
 565         uint32_t reserved__; /* For alignment */
 566 };
 567
 568 struct aux_event {
 569         struct perf_event_header header;
 570         uint64_t        aux_offset;
 571         uint64_t        aux_size;
 572         uint64_t        flags;
 573 };
 574
 575         PERF_RECORD_AUXTRACE_ERROR              = 72,
 576
 577 Describes an error in hardware tracing
 578
 579 enum auxtrace_error_type {
 580         PERF_AUXTRACE_ERROR_ITRACE  = 1,
 581         PERF_AUXTRACE_ERROR_MAX
 582 };
 583
 584 #define MAX_AUXTRACE_ERROR_MSG 64
 585
 586 struct auxtrace_error_event {
 587         struct perf_event_header header;
 588         uint32_t type;
 589         uint32_t code;
 590         uint32_t cpu;
 591         uint32_t pid;
 592         uint32_t tid;
 593         uint32_t reserved__; /* For alignment */
 594         uint64_t ip;
 595         char msg[MAX_AUXTRACE_ERROR_MSG];
 596 };
 597
 598         PERF_RECORD_HEADER_FEATURE              = 80,
 599
 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.
 602
 603         PERF_RECORD_COMPRESSED                  = 81,
 604
 605 struct compressed_event {
 606         struct perf_event_header        header;
 607         char                            data[];
 608 };
 609
 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.
 613
 614 Event types
 615
 616 Define the event attributes with their IDs.
 617
 618 An array bound by the perf_file_section size.
 619
 620         struct {
 621                 struct perf_event_attr attr;   /* Size defined by header.attr_size */
 622                 struct perf_file_section ids;
 623         }
 624
 625 ids points to a array of uint64_t defining the ids for event attr attr.
 626
 627 Pipe-mode data
 628
 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:
 631
 632 struct perf_pipe_file_header {
 633         u64                             magic;
 634         u64                             size;
 635 };
 636
 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.
 641
 642
 643 References:
 644
 645 include/uapi/linux/perf_event.h
 646
 647 This is the canonical description of the kernel generated perf_events
 648 and the perf_event_attrs.
 649
 650 perf_events manpage
 651
 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
 657 perf_events"
 658
 659 pmu-tools
 660
 661 https://github.com/andikleen/pmu-tools/tree/master/parser
 662
 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.
 665
 666 quipper
 667
 668 The quipper C++ parser is available at
 669 http://github.com/google/perf_data_converter/tree/master/src/quipper
 670