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 bytes.
 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 String lists defining the core and CPU threads topology.
 155 The string lists are followed by a variable length array
 156 which contains core_id, die_id (for x86) and socket_id of each cpu.
 157 The number of entries can be determined by the size of the
 158 section minus the sizes of both string lists.
 159
 160 struct {
 161        struct perf_header_string_list cores; /* Variable length */
 162        struct perf_header_string_list threads; /* Variable length */
 163        struct {
 164               uint32_t core_id;
 165               uint32_t die_id;
 166               uint32_t socket_id;
 167        } cpus[nr]; /* Variable length records */
 168 };
 169
 170 Example:
 171         sibling sockets : 0-8
 172         sibling dies    : 0-3
 173         sibling dies    : 4-7
 174         sibling threads : 0-1
 175         sibling threads : 2-3
 176         sibling threads : 4-5
 177         sibling threads : 6-7
 178
 179         HEADER_NUMA_TOPOLOGY = 14,
 180
 181         A list of NUMA node descriptions
 182
 183 struct {
 184        uint32_t nr;
 185        struct {
 186               uint32_t nodenr;
 187               uint64_t mem_total;
 188               uint64_t mem_free;
 189               struct perf_header_string cpus;
 190        } nodes[nr]; /* Variable length records */
 191 };
 192
 193         HEADER_BRANCH_STACK = 15,
 194
 195 Not implemented in perf.
 196
 197         HEADER_PMU_MAPPINGS = 16,
 198
 199         A list of PMU structures, defining the different PMUs supported by perf.
 200
 201 struct {
 202        uint32_t nr;
 203        struct pmu {
 204               uint32_t pmu_type;
 205               struct perf_header_string pmu_name;
 206        } [nr]; /* Variable length records */
 207 };
 208
 209         HEADER_GROUP_DESC = 17,
 210
 211         Description of counter groups ({...} in perf syntax)
 212
 213 struct {
 214          uint32_t nr;
 215          struct {
 216                 struct perf_header_string string;
 217                 uint32_t leader_idx;
 218                 uint32_t nr_members;
 219          } [nr]; /* Variable length records */
 220 };
 221
 222         HEADER_AUXTRACE = 18,
 223
 224 Define additional auxtrace areas in the perf.data. auxtrace is used to store
 225 undecoded hardware tracing information, such as Intel Processor Trace data.
 226
 227 /**
 228  * struct auxtrace_index_entry - indexes a AUX area tracing event within a
 229  *                               perf.data file.
 230  * @file_offset: offset within the perf.data file
 231  * @sz: size of the event
 232  */
 233 struct auxtrace_index_entry {
 234         u64                     file_offset;
 235         u64                     sz;
 236 };
 237
 238 #define PERF_AUXTRACE_INDEX_ENTRY_COUNT 256
 239
 240 /**
 241  * struct auxtrace_index - index of AUX area tracing events within a perf.data
 242  *                         file.
 243  * @list: linking a number of arrays of entries
 244  * @nr: number of entries
 245  * @entries: array of entries
 246  */
 247 struct auxtrace_index {
 248         struct list_head        list;
 249         size_t                  nr;
 250         struct auxtrace_index_entry entries[PERF_AUXTRACE_INDEX_ENTRY_COUNT];
 251 };
 252
 253         HEADER_STAT = 19,
 254
 255 This is merely a flag signifying that the data section contains data
 256 recorded from perf stat record.
 257
 258         HEADER_CACHE = 20,
 259
 260 Description of the cache hierarchy. Based on the Linux sysfs format
 261 in /sys/devices/system/cpu/cpu*/cache/
 262
 263         u32 version     Currently always 1
 264         u32 number_of_cache_levels
 265
 266 struct {
 267         u32     level;
 268         u32     line_size;
 269         u32     sets;
 270         u32     ways;
 271         struct perf_header_string type;
 272         struct perf_header_string size;
 273         struct perf_header_string map;
 274 }[number_of_cache_levels];
 275
 276         HEADER_SAMPLE_TIME = 21,
 277
 278 Two uint64_t for the time of first sample and the time of last sample.
 279
 280         HEADER_SAMPLE_TOPOLOGY = 22,
 281
 282 Physical memory map and its node assignments.
 283
 284 The format of data in MEM_TOPOLOGY is as follows:
 285
 286    0 - version          | for future changes
 287    8 - block_size_bytes | /sys/devices/system/memory/block_size_bytes
 288   16 - count            | number of nodes
 289
 290 For each node we store map of physical indexes:
 291
 292   32 - node id          | node index
 293   40 - size             | size of bitmap
 294   48 - bitmap           | bitmap of memory indexes that belongs to node
 295                         | /sys/devices/system/node/node<NODE>/memory<INDEX>
 296
 297 The MEM_TOPOLOGY can be displayed with following command:
 298
 299 $ perf report --header-only -I
 300 ...
 301 # memory nodes (nr 1, block size 0x8000000):
 302 #    0 [7G]: 0-23,32-69
 303
 304         HEADER_CLOCKID = 23,
 305
 306 One uint64_t for the clockid frequency, specified, for instance, via 'perf
 307 record -k' (see clock_gettime()), to enable timestamps derived metrics
 308 conversion into wall clock time on the reporting stage.
 309
 310         HEADER_DIR_FORMAT = 24,
 311
 312 The data files layout is described by HEADER_DIR_FORMAT feature.  Currently it
 313 holds only version number (1):
 314
 315   uint64_t version;
 316
 317 The current version holds only version value (1) means that data files:
 318
 319 - Follow the 'data.*' name format.
 320
 321 - Contain raw events data in standard perf format as read from kernel (and need
 322   to be sorted)
 323
 324 Future versions are expected to describe different data files layout according
 325 to special needs.
 326
 327         HEADER_BPF_PROG_INFO = 25,
 328
 329 struct bpf_prog_info_linear, which contains detailed information about
 330 a BPF program, including type, id, tag, jited/xlated instructions, etc.
 331
 332         HEADER_BPF_BTF = 26,
 333
 334 Contains BPF Type Format (BTF). For more information about BTF, please
 335 refer to Documentation/bpf/btf.rst.
 336
 337 struct {
 338         u32     id;
 339         u32     data_size;
 340         char    data[];
 341 };
 342
 343         HEADER_COMPRESSED = 27,
 344
 345 struct {
 346         u32     version;
 347         u32     type;
 348         u32     level;
 349         u32     ratio;
 350         u32     mmap_len;
 351 };
 352
 353 Indicates that trace contains records of PERF_RECORD_COMPRESSED type
 354 that have perf_events records in compressed form.
 355
 356         other bits are reserved and should ignored for now
 357         HEADER_FEAT_BITS        = 256,
 358
 359 Attributes
 360
 361 This is an array of perf_event_attrs, each attr_size bytes long, which defines
 362 each event collected. See perf_event.h or the man page for a detailed
 363 description.
 364
 365 Data
 366
 367 This section is the bulk of the file. It consist of a stream of perf_events
 368 describing events. This matches the format generated by the kernel.
 369 See perf_event.h or the manpage for a detailed description.
 370
 371 Some notes on parsing:
 372
 373 Ordering
 374
 375 The events are not necessarily in time stamp order, as they can be
 376 collected in parallel on different CPUs. If the events should be
 377 processed in time order they need to be sorted first. It is possible
 378 to only do a partial sort using the FINISHED_ROUND event header (see
 379 below). perf record guarantees that there is no reordering over a
 380 FINISHED_ROUND.
 381
 382 ID vs IDENTIFIER
 383
 384 When the event stream contains multiple events each event is identified
 385 by an ID. This can be either through the PERF_SAMPLE_ID or the
 386 PERF_SAMPLE_IDENTIFIER header. The PERF_SAMPLE_IDENTIFIER header is
 387 at a fixed offset from the event header, which allows reliable
 388 parsing of the header. Relying on ID may be ambiguous.
 389 IDENTIFIER is only supported by newer Linux kernels.
 390
 391 Perf record specific events:
 392
 393 In addition to the kernel generated event types perf record adds its
 394 own event types (in addition it also synthesizes some kernel events,
 395 for example MMAP events)
 396
 397         PERF_RECORD_USER_TYPE_START             = 64,
 398         PERF_RECORD_HEADER_ATTR                 = 64,
 399
 400 struct attr_event {
 401         struct perf_event_header header;
 402         struct perf_event_attr attr;
 403         uint64_t id[];
 404 };
 405
 406         PERF_RECORD_HEADER_EVENT_TYPE           = 65, /* deprecated */
 407
 408 #define MAX_EVENT_NAME 64
 409
 410 struct perf_trace_event_type {
 411         uint64_t        event_id;
 412         char    name[MAX_EVENT_NAME];
 413 };
 414
 415 struct event_type_event {
 416         struct perf_event_header header;
 417         struct perf_trace_event_type event_type;
 418 };
 419
 420
 421         PERF_RECORD_HEADER_TRACING_DATA         = 66,
 422
 423 Describe me
 424
 425 struct tracing_data_event {
 426         struct perf_event_header header;
 427         uint32_t size;
 428 };
 429
 430         PERF_RECORD_HEADER_BUILD_ID             = 67,
 431
 432 Define a ELF build ID for a referenced executable.
 433
 434        struct build_id_event;   /* See above */
 435
 436         PERF_RECORD_FINISHED_ROUND              = 68,
 437
 438 No event reordering over this header. No payload.
 439
 440         PERF_RECORD_ID_INDEX                    = 69,
 441
 442 Map event ids to CPUs and TIDs.
 443
 444 struct id_index_entry {
 445         uint64_t id;
 446         uint64_t idx;
 447         uint64_t cpu;
 448         uint64_t tid;
 449 };
 450
 451 struct id_index_event {
 452         struct perf_event_header header;
 453         uint64_t nr;
 454         struct id_index_entry entries[nr];
 455 };
 456
 457         PERF_RECORD_AUXTRACE_INFO               = 70,
 458
 459 Auxtrace type specific information. Describe me
 460
 461 struct auxtrace_info_event {
 462         struct perf_event_header header;
 463         uint32_t type;
 464         uint32_t reserved__; /* For alignment */
 465         uint64_t priv[];
 466 };
 467
 468         PERF_RECORD_AUXTRACE                    = 71,
 469
 470 Defines auxtrace data. Followed by the actual data. The contents of
 471 the auxtrace data is dependent on the event and the CPU. For example
 472 for Intel Processor Trace it contains Processor Trace data generated
 473 by the CPU.
 474
 475 struct auxtrace_event {
 476         struct perf_event_header header;
 477         uint64_t size;
 478         uint64_t offset;
 479         uint64_t reference;
 480         uint32_t idx;
 481         uint32_t tid;
 482         uint32_t cpu;
 483         uint32_t reserved__; /* For alignment */
 484 };
 485
 486 struct aux_event {
 487         struct perf_event_header header;
 488         uint64_t        aux_offset;
 489         uint64_t        aux_size;
 490         uint64_t        flags;
 491 };
 492
 493         PERF_RECORD_AUXTRACE_ERROR              = 72,
 494
 495 Describes an error in hardware tracing
 496
 497 enum auxtrace_error_type {
 498         PERF_AUXTRACE_ERROR_ITRACE  = 1,
 499         PERF_AUXTRACE_ERROR_MAX
 500 };
 501
 502 #define MAX_AUXTRACE_ERROR_MSG 64
 503
 504 struct auxtrace_error_event {
 505         struct perf_event_header header;
 506         uint32_t type;
 507         uint32_t code;
 508         uint32_t cpu;
 509         uint32_t pid;
 510         uint32_t tid;
 511         uint32_t reserved__; /* For alignment */
 512         uint64_t ip;
 513         char msg[MAX_AUXTRACE_ERROR_MSG];
 514 };
 515
 516         PERF_RECORD_HEADER_FEATURE              = 80,
 517
 518 Describes a header feature. These are records used in pipe-mode that
 519 contain information that otherwise would be in perf.data file's header.
 520
 521         PERF_RECORD_COMPRESSED                  = 81,
 522
 523 struct compressed_event {
 524         struct perf_event_header        header;
 525         char                            data[];
 526 };
 527
 528 The header is followed by compressed data frame that can be decompressed
 529 into array of perf trace records. The size of the entire compressed event
 530 record including the header is limited by the max value of header.size.
 531
 532 Event types
 533
 534 Define the event attributes with their IDs.
 535
 536 An array bound by the perf_file_section size.
 537
 538         struct {
 539                 struct perf_event_attr attr;   /* Size defined by header.attr_size */
 540                 struct perf_file_section ids;
 541         }
 542
 543 ids points to a array of uint64_t defining the ids for event attr attr.
 544
 545 Pipe-mode data
 546
 547 Pipe-mode avoid seeks in the file by removing the perf_file_section and flags
 548 from the struct perf_header. The trimmed header is:
 549
 550 struct perf_pipe_file_header {
 551         u64                             magic;
 552         u64                             size;
 553 };
 554
 555 The information about attrs, data, and event_types is instead in the
 556 synthesized events PERF_RECORD_ATTR, PERF_RECORD_HEADER_TRACING_DATA,
 557 PERF_RECORD_HEADER_EVENT_TYPE, and PERF_RECORD_HEADER_FEATURE
 558 that are generated by perf record in pipe-mode.
 559
 560
 561 References:
 562
 563 include/uapi/linux/perf_event.h
 564
 565 This is the canonical description of the kernel generated perf_events
 566 and the perf_event_attrs.
 567
 568 perf_events manpage
 569
 570 A manpage describing perf_event and perf_event_attr is here:
 571 http://web.eece.maine.edu/~vweaver/projects/perf_events/programming.html
 572 This tends to be slightly behind the kernel include, but has better
 573 descriptions.  An (typically older) version of the man page may be
 574 included with the standard Linux man pages, available with "man
 575 perf_events"
 576
 577 pmu-tools
 578
 579 https://github.com/andikleen/pmu-tools/tree/master/parser
 580
 581 A definition of the perf.data format in python "construct" format is available
 582 in pmu-tools parser. This allows to read perf.data from python and dump it.
 583
 584 quipper
 585
 586 The quipper C++ parser is available at
 587 http://github.com/google/perf_data_converter/tree/master/src/quipper
 588