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 The header is followed by different optional headers, described by the bits set
  47 in flags. Only headers for which the bit is set are included. Each header
  48 consists of a perf_file_section located after the initial header.
  49 The respective perf_file_section points to the data of the additional
  50 header and defines its size.
  51
  52 Some headers consist of strings, which are defined like this:
  53
  54 struct perf_header_string {
  55        uint32_t len;
  56        char string[len]; /* zero terminated */
  57 };
  58
  59 Some headers consist of a sequence of strings, which start with a
  60
  61 struct perf_header_string_list {
  62      uint32_t nr;
  63      struct perf_header_string strings[nr]; /* variable length records */
  64 };
  65
  66 The bits are the flags bits in a 256 bit bitmap starting with
  67 flags. These define the valid bits:
  68
  69         HEADER_RESERVED         = 0,    /* always cleared */
  70         HEADER_FIRST_FEATURE    = 1,
  71         HEADER_TRACING_DATA     = 1,
  72
  73 Describe me.
  74
  75         HEADER_BUILD_ID = 2,
  76
  77 The header consists of an sequence of build_id_event. The size of each record
  78 is defined by header.size (see perf_event.h). Each event defines a ELF build id
  79 for a executable file name for a pid. An ELF build id is a unique identifier
  80 assigned by the linker to an executable.
  81
  82 struct build_id_event {
  83         struct perf_event_header header;
  84         pid_t                    pid;
  85         uint8_t                  build_id[24];
  86         char                     filename[header.size - offsetof(struct build_id_event, filename)];
  87 };
  88
  89         HEADER_HOSTNAME = 3,
  90
  91 A perf_header_string with the hostname where the data was collected
  92 (uname -n)
  93
  94         HEADER_OSRELEASE = 4,
  95
  96 A perf_header_string with the os release where the data was collected
  97 (uname -r)
  98
  99         HEADER_VERSION = 5,
 100
 101 A perf_header_string with the perf user tool version where the
 102 data was collected. This is the same as the version of the source tree
 103 the perf tool was built from.
 104
 105         HEADER_ARCH = 6,
 106
 107 A perf_header_string with the CPU architecture (uname -m)
 108
 109         HEADER_NRCPUS = 7,
 110
 111 A structure defining the number of CPUs.
 112
 113 struct nr_cpus {
 114        uint32_t nr_cpus_available; /* CPUs not yet onlined */
 115        uint32_t nr_cpus_online;
 116 };
 117
 118         HEADER_CPUDESC = 8,
 119
 120 A perf_header_string with description of the CPU. On x86 this is the model name
 121 in /proc/cpuinfo
 122
 123         HEADER_CPUID = 9,
 124
 125 A perf_header_string with the exact CPU type. On x86 this is
 126 vendor,family,model,stepping. For example: GenuineIntel,6,69,1
 127
 128         HEADER_TOTAL_MEM = 10,
 129
 130 An uint64_t with the total memory in bytes.
 131
 132         HEADER_CMDLINE = 11,
 133
 134 A perf_header_string with the perf command line used to collect the data.
 135
 136         HEADER_EVENT_DESC = 12,
 137
 138 Another description of the perf_event_attrs, more detailed than header.attrs
 139 including IDs and names. See perf_event.h or the man page for a description
 140 of a struct perf_event_attr.
 141
 142 struct {
 143        uint32_t nr; /* number of events */
 144        uint32_t attr_size; /* size of each perf_event_attr */
 145        struct {
 146               struct perf_event_attr attr;  /* size of attr_size */
 147               uint32_t nr_ids;
 148               struct perf_header_string event_string;
 149               uint64_t ids[nr_ids];
 150        } events[nr]; /* Variable length records */
 151 };
 152
 153         HEADER_CPU_TOPOLOGY = 13,
 154
 155 String lists defining the core and CPU threads topology.
 156 The string lists are followed by a variable length array
 157 which contains core_id and socket_id of each cpu.
 158 The number of entries can be determined by the size of the
 159 section minus the sizes of both string lists.
 160
 161 struct {
 162        struct perf_header_string_list cores; /* Variable length */
 163        struct perf_header_string_list threads; /* Variable length */
 164        struct {
 165               uint32_t core_id;
 166               uint32_t socket_id;
 167        } cpus[nr]; /* Variable length records */
 168 };
 169
 170 Example:
 171         sibling cores   : 0-3
 172         sibling threads : 0-1
 173         sibling threads : 2-3
 174
 175         HEADER_NUMA_TOPOLOGY = 14,
 176
 177         A list of NUMA node descriptions
 178
 179 struct {
 180        uint32_t nr;
 181        struct {
 182               uint32_t nodenr;
 183               uint64_t mem_total;
 184               uint64_t mem_free;
 185               struct perf_header_string cpus;
 186        } nodes[nr]; /* Variable length records */
 187 };
 188
 189         HEADER_BRANCH_STACK = 15,
 190
 191 Not implemented in perf.
 192
 193         HEADER_PMU_MAPPINGS = 16,
 194
 195         A list of PMU structures, defining the different PMUs supported by perf.
 196
 197 struct {
 198        uint32_t nr;
 199        struct pmu {
 200               uint32_t pmu_type;
 201               struct perf_header_string pmu_name;
 202        } [nr]; /* Variable length records */
 203 };
 204
 205         HEADER_GROUP_DESC = 17,
 206
 207         Description of counter groups ({...} in perf syntax)
 208
 209 struct {
 210          uint32_t nr;
 211          struct {
 212                 struct perf_header_string string;
 213                 uint32_t leader_idx;
 214                 uint32_t nr_members;
 215          } [nr]; /* Variable length records */
 216 };
 217
 218         HEADER_AUXTRACE = 18,
 219
 220 Define additional auxtrace areas in the perf.data. auxtrace is used to store
 221 undecoded hardware tracing information, such as Intel Processor Trace data.
 222
 223 /**
 224  * struct auxtrace_index_entry - indexes a AUX area tracing event within a
 225  *                               perf.data file.
 226  * @file_offset: offset within the perf.data file
 227  * @sz: size of the event
 228  */
 229 struct auxtrace_index_entry {
 230         u64                     file_offset;
 231         u64                     sz;
 232 };
 233
 234 #define PERF_AUXTRACE_INDEX_ENTRY_COUNT 256
 235
 236 /**
 237  * struct auxtrace_index - index of AUX area tracing events within a perf.data
 238  *                         file.
 239  * @list: linking a number of arrays of entries
 240  * @nr: number of entries
 241  * @entries: array of entries
 242  */
 243 struct auxtrace_index {
 244         struct list_head        list;
 245         size_t                  nr;
 246         struct auxtrace_index_entry entries[PERF_AUXTRACE_INDEX_ENTRY_COUNT];
 247 };
 248
 249         HEADER_STAT = 19,
 250
 251 This is merely a flag signifying that the data section contains data
 252 recorded from perf stat record.
 253
 254         HEADER_CACHE = 20,
 255
 256 Description of the cache hierarchy. Based on the Linux sysfs format
 257 in /sys/devices/system/cpu/cpu*/cache/
 258
 259         u32 version     Currently always 1
 260         u32 number_of_cache_levels
 261
 262 struct {
 263         u32     level;
 264         u32     line_size;
 265         u32     sets;
 266         u32     ways;
 267         struct perf_header_string type;
 268         struct perf_header_string size;
 269         struct perf_header_string map;
 270 }[number_of_cache_levels];
 271
 272         HEADER_SAMPLE_TIME = 21,
 273
 274 Two uint64_t for the time of first sample and the time of last sample.
 275
 276         other bits are reserved and should ignored for now
 277         HEADER_FEAT_BITS        = 256,
 278
 279 Attributes
 280
 281 This is an array of perf_event_attrs, each attr_size bytes long, which defines
 282 each event collected. See perf_event.h or the man page for a detailed
 283 description.
 284
 285 Data
 286
 287 This section is the bulk of the file. It consist of a stream of perf_events
 288 describing events. This matches the format generated by the kernel.
 289 See perf_event.h or the manpage for a detailed description.
 290
 291 Some notes on parsing:
 292
 293 Ordering
 294
 295 The events are not necessarily in time stamp order, as they can be
 296 collected in parallel on different CPUs. If the events should be
 297 processed in time order they need to be sorted first. It is possible
 298 to only do a partial sort using the FINISHED_ROUND event header (see
 299 below). perf record guarantees that there is no reordering over a
 300 FINISHED_ROUND.
 301
 302 ID vs IDENTIFIER
 303
 304 When the event stream contains multiple events each event is identified
 305 by an ID. This can be either through the PERF_SAMPLE_ID or the
 306 PERF_SAMPLE_IDENTIFIER header. The PERF_SAMPLE_IDENTIFIER header is
 307 at a fixed offset from the event header, which allows reliable
 308 parsing of the header. Relying on ID may be ambiguous.
 309 IDENTIFIER is only supported by newer Linux kernels.
 310
 311 Perf record specific events:
 312
 313 In addition to the kernel generated event types perf record adds its
 314 own event types (in addition it also synthesizes some kernel events,
 315 for example MMAP events)
 316
 317         PERF_RECORD_USER_TYPE_START             = 64,
 318         PERF_RECORD_HEADER_ATTR                 = 64,
 319
 320 struct attr_event {
 321         struct perf_event_header header;
 322         struct perf_event_attr attr;
 323         uint64_t id[];
 324 };
 325
 326         PERF_RECORD_HEADER_EVENT_TYPE           = 65, /* deprecated */
 327
 328 #define MAX_EVENT_NAME 64
 329
 330 struct perf_trace_event_type {
 331         uint64_t        event_id;
 332         char    name[MAX_EVENT_NAME];
 333 };
 334
 335 struct event_type_event {
 336         struct perf_event_header header;
 337         struct perf_trace_event_type event_type;
 338 };
 339
 340
 341         PERF_RECORD_HEADER_TRACING_DATA         = 66,
 342
 343 Describe me
 344
 345 struct tracing_data_event {
 346         struct perf_event_header header;
 347         uint32_t size;
 348 };
 349
 350         PERF_RECORD_HEADER_BUILD_ID             = 67,
 351
 352 Define a ELF build ID for a referenced executable.
 353
 354        struct build_id_event;   /* See above */
 355
 356         PERF_RECORD_FINISHED_ROUND              = 68,
 357
 358 No event reordering over this header. No payload.
 359
 360         PERF_RECORD_ID_INDEX                    = 69,
 361
 362 Map event ids to CPUs and TIDs.
 363
 364 struct id_index_entry {
 365         uint64_t id;
 366         uint64_t idx;
 367         uint64_t cpu;
 368         uint64_t tid;
 369 };
 370
 371 struct id_index_event {
 372         struct perf_event_header header;
 373         uint64_t nr;
 374         struct id_index_entry entries[nr];
 375 };
 376
 377         PERF_RECORD_AUXTRACE_INFO               = 70,
 378
 379 Auxtrace type specific information. Describe me
 380
 381 struct auxtrace_info_event {
 382         struct perf_event_header header;
 383         uint32_t type;
 384         uint32_t reserved__; /* For alignment */
 385         uint64_t priv[];
 386 };
 387
 388         PERF_RECORD_AUXTRACE                    = 71,
 389
 390 Defines auxtrace data. Followed by the actual data. The contents of
 391 the auxtrace data is dependent on the event and the CPU. For example
 392 for Intel Processor Trace it contains Processor Trace data generated
 393 by the CPU.
 394
 395 struct auxtrace_event {
 396         struct perf_event_header header;
 397         uint64_t size;
 398         uint64_t offset;
 399         uint64_t reference;
 400         uint32_t idx;
 401         uint32_t tid;
 402         uint32_t cpu;
 403         uint32_t reserved__; /* For alignment */
 404 };
 405
 406 struct aux_event {
 407         struct perf_event_header header;
 408         uint64_t        aux_offset;
 409         uint64_t        aux_size;
 410         uint64_t        flags;
 411 };
 412
 413         PERF_RECORD_AUXTRACE_ERROR              = 72,
 414
 415 Describes an error in hardware tracing
 416
 417 enum auxtrace_error_type {
 418         PERF_AUXTRACE_ERROR_ITRACE  = 1,
 419         PERF_AUXTRACE_ERROR_MAX
 420 };
 421
 422 #define MAX_AUXTRACE_ERROR_MSG 64
 423
 424 struct auxtrace_error_event {
 425         struct perf_event_header header;
 426         uint32_t type;
 427         uint32_t code;
 428         uint32_t cpu;
 429         uint32_t pid;
 430         uint32_t tid;
 431         uint32_t reserved__; /* For alignment */
 432         uint64_t ip;
 433         char msg[MAX_AUXTRACE_ERROR_MSG];
 434 };
 435
 436         PERF_RECORD_HEADER_FEATURE              = 80,
 437
 438 Describes a header feature. These are records used in pipe-mode that
 439 contain information that otherwise would be in perf.data file's header.
 440
 441 Event types
 442
 443 Define the event attributes with their IDs.
 444
 445 An array bound by the perf_file_section size.
 446
 447         struct {
 448                 struct perf_event_attr attr;   /* Size defined by header.attr_size */
 449                 struct perf_file_section ids;
 450         }
 451
 452 ids points to a array of uint64_t defining the ids for event attr attr.
 453
 454 Pipe-mode data
 455
 456 Pipe-mode avoid seeks in the file by removing the perf_file_section and flags
 457 from the struct perf_header. The trimmed header is:
 458
 459 struct perf_pipe_file_header {
 460         u64                             magic;
 461         u64                             size;
 462 };
 463
 464 The information about attrs, data, and event_types is instead in the
 465 synthesized events PERF_RECORD_ATTR, PERF_RECORD_HEADER_TRACING_DATA,
 466 PERF_RECORD_HEADER_EVENT_TYPE, and PERF_RECORD_HEADER_FEATURE
 467 that are generated by perf record in pipe-mode.
 468
 469
 470 References:
 471
 472 include/uapi/linux/perf_event.h
 473
 474 This is the canonical description of the kernel generated perf_events
 475 and the perf_event_attrs.
 476
 477 perf_events manpage
 478
 479 A manpage describing perf_event and perf_event_attr is here:
 480 http://web.eece.maine.edu/~vweaver/projects/perf_events/programming.html
 481 This tends to be slightly behind the kernel include, but has better
 482 descriptions.  An (typically older) version of the man page may be
 483 included with the standard Linux man pages, available with "man
 484 perf_events"
 485
 486 pmu-tools
 487
 488 https://github.com/andikleen/pmu-tools/tree/master/parser
 489
 490 A definition of the perf.data format in python "construct" format is available
 491 in pmu-tools parser. This allows to read perf.data from python and dump it.
 492
 493 quipper
 494
 495 The quipper C++ parser is available at
 496 http://github.com/google/perf_data_converter/tree/master/src/quipper
 497