STRUCT PERF_SESSION(9)

💜 struct perf_session(9) 💜

ok so bestie, welcome to struct perf_session(9) — the Kernel API Manual page for one of perf's biggest main-character structs. lowkey iconic. no cap.

---

✨ NAME ✨

struct perf_session — bestie this is A Perf session, and it's literally the struct that holds the main state when the program is working with live perf events or reading data from an input file. it's giving "the whole vibe lives here." 🫶

---

🦋 SYNOPSIS 🦋

struct perf_session {
    struct perf_header      header;
    struct machines         machines;
    struct evlist   *evlist;
    const struct auxtrace   *auxtrace;
    struct itrace_synth_opts *itrace_synth_opts;
    struct list_head        auxtrace_index;
  #ifdef HAVE_LIBTRACEEVENT;
    struct trace_event      tevent;
  #endif;
    struct perf_record_time_conv    time_conv;
    bool trace_event_repipe;
    bool one_mmap;
    void *one_mmap_addr;
    u64 one_mmap_offset;
    u64 one_mmap_size;
    struct ordered_events   ordered_events;
    struct perf_data        *data;
    const struct perf_tool  *tool;
    u64 bytes_transferred;
    u64 bytes_compressed;
    struct zstd_data        zstd_data;
    struct decomp_data      decomp_data;
    struct decomp_data      *active_decomp;
 };

copy it exactly, bestie, don't go editing it, that's the whole point 🙈

---

🎀 MEMBERS 🎀

okay now the fun part — let's meet the whole squad, member by member, no skipping, we go through ALL of them 💅

• header — the read version of a perf_file_header, or it captures global information from a live session. either way it's carrying the lore.
• machines — Machines within the session: a host and 0 or more guests. the whole little family 🌸
• evlist — List of evsels/events of the session. the actual events, the stars of the show ⭐
• auxtrace — callbacks to allow AUX area data decoding. lowkey the decoder ring 🔥
• itrace_synth_opts — AUX area tracing synthesis options. all the knobs for synthesis, slay.
• auxtrace_index — index of AUX area tracing events within a perf.data file. the findability agenda ✨
• tevent — handles for libtraceevent and plugins. (only hangs around when HAVE_LIBTRACEEVENT is defined, iykyk 🦋)
• time_conv — Holds contents of last PERF_RECORD_TIME_CONV event. time math, but make it stored 💫
• trace_event_repipe — When set, causes read trace events to be written to stdout. yes, set it and it's repipe girl summer.
• one_mmap — The reader will use a single mmap by default. There may be multiple data files, in particular for aux events. If this is true then the single big mmap for the data file can be assumed. big one-mmap energy.
• one_mmap_addr — Address of initial perf data file reader mmap. the address, periodt.
• one_mmap_offset — File offset in perf.data file when mapped.
• one_mmap_size — Size of the single mmap, in bytes. it's a size. in bytes. respect it 🫶
• ordered_events — Used to turn unordered events into ordered ones. literally the glow-up machine for your event ordering 😭
• data — Optional perf data file being read from. optional bestie, don't assume.
• tool — callbacks for event handling. the handlers, the crew, the ones who do the doing 💅
• bytes_transferred — Used by perf record to count written bytes before compression.
• bytes_compressed — Used by perf record to count written bytes after compression. yes it's a different count, keep both, don't merge them 🙈
• zstd_data — Owner of global compression state, buffers, etc. it holds the compression stuff, it's the owner, it's the moment 👑
• decomp_data — decompression data, chillin' right there in the struct.
• decomp_data *active_decomp — a pointer to the decompression data that's currently active. the one on duty 🧚

---

🌈 DESCRIPTION 🌈

kay so The rough organization of a perf_session is literally this, like, whole tree vibe:

┌────────────────────────────────────────────────────────┐
│ Session   1..* ----->   Machine   1..* ----->   Thread │
└────────────────────────────────────────────────────────┘

a Session points to 1..* Machines, and each Machine points to 1..* Threads. it's giving nesting dolls. it's giving family tree. it's giving the whole hierarchy eaten and left no crumbs 🍓

---

🔥 SEE ALSO 🔥

• Kernel file ./tools/perf/util/session.h — go read it, bestie, that's where the real tea is 🦋

---

and that's the page!! sending you so much love and also a single big mmap 💖 from ./tools/perf/util, dated October 2026 — mwah, go slay your perf session bestie 🎀✨👑