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