STRUCT PERF_SAMPLE(9)

📦 version 7.3.1, in nixpkgs unstable

💅 struct perf_sample(9) — the Kernel API Manual, but make it make sense 🎀

okay bestie, so this page is from the Kernel API Manual and it's literally all about struct perf_sample — the little glow-up container that holds one perf sample so you don't have to rawdog the variable-length event yourself. Let's get into it ✨

✨ NAME ✨

struct perf_sample — the struct that says "I got you" for one perf sample event 💖

(the original name section is literally just the struct name with a dash, no cap, that's it)

🫶 SYNOPSIS 🫶

here's the whole struct, character for character, because bestie we do not paraphrase code:

struct perf_sample {
    struct evsel *evsel;
    u64 ip;
    u32 pid;
    u32 tid;
    u64 time;
    u64 addr;
    u64 id;
    u64 stream_id;
    u64 period;
    u64 weight;
    u64 transaction;
    u64 insn_cnt;
    u64 cyc_cnt;
    u32 cpu;
    u32 raw_size;
    u64 data_src;
    u64 phys_addr;
    u64 data_page_size;
    u64 code_page_size;
    u64 cgroup;
    u64 file_offset;
    u32 flags;
    u32 machine_pid;
    u32 vcpu;
    u16 insn_len;
    u16 misc;
    u16 ins_lat;
    u16 weight3;
    u8 cpumode;
    bool no_hw_idx;
    bool deferred_callchain;
    bool merged_callchain;
    u64 deferred_cookie;
    char insn[MAX_INSN];
    void *raw_data;
    struct ip_callchain *callchain;
    struct branch_stack *branch_stack;
    u64 *branch_stack_cntr;
    struct regs_dump  *user_regs;
    struct regs_dump  *intr_regs;
    struct stack_dump user_stack;
    struct sample_read read;
    struct aux_sample aux_sample;
    struct simd_flags simd_flags;
 };

like, look at her. main character struct energy 👑

🌸 Members 🌸

okay so every single one of these fields, and what it actually means:

  • evsel — backward reference to the evsel that was used when constructing the sample. it's giving "who's your parent" energy.
  • ip — the sample event PERF_SAMPLE_IP value. the instruction pointer, bestie.
  • pid — the sample event PERF_SAMPLE_TID pid value.
  • tid — the sample event PERF_SAMPLE_TID tid value.
  • time — the sample event PERF_SAMPLE_TIME value.
  • addr — the sample event PERF_SAMPLE_ADDR value.
  • id — the sample event PERF_SAMPLE_ID or PERF_SAMPLE_IDENTIFIER value.
  • stream_id — the sample event PERF_SAMPLE_STREAM_ID value.
  • period — the sample event PERF_SAMPLE_PERIOD value.
  • weight — data determined by PERF_SAMPLE_WEIGHT or PERF_SAMPLE_WEIGHT_STRUCT. two sources, one field, she's versatile like that 💅
  • transaction — the sample event PERF_SAMPLE_TRANSACTION value.
  • insn_cnt — filled in and used by intel-pt.
  • cyc_cnt — filled in and used by intel-pt. (yes, the intel-pt girlies get two fields, we love that for them)
  • cpu — the sample event PERF_SAMPLE_CPU value.
  • raw_size — the size in bytes of raw data from PERF_SAMPLE_RAW. ⚠️ for alignment reasons this should always be sizeof(u32) followed by a multiple of sizeof(u64). like, always. don't fight the alignment, bestie.
  • data_src — the sample event PERF_SAMPLE_DATA_SRC value.
  • phys_addr — the sample event PERF_SAMPLE_PHYS_ADDR value.
  • data_page_size — the sample event PERF_SAMPLE_DATA_PAGE_SIZE value.
  • code_page_size — the sample event PERF_SAMPLE_CODE_PAGE_SIZE value.
  • cgroup — the sample event PERF_SAMPLE_CGROUP value.
  • file_offset — byte offset of this event in the perf.data file. iykyk 📍
  • flags — extra flag data from auxiliary events like intel-pt.
  • machine_pid — the guest machine pid, derived from the sample id.
  • vcpu — the guest machine vcpu, derived from the sample id.
  • insn_len — instruction length from auxiliary events like intel-pt. the instruction itself is held in insn. see, teamwork 🫶
  • misc — the entire struct perf_event_header misc variable. the whole thing. she's not doing halves.
  • ins_lat — instruction latency information from weight2 in PERF_SAMPLE_WEIGHT_STRUCT, or from auxiliary events like intel-pt.
  • weight3 — from PERF_SAMPLE_WEIGHT_STRUCT. on x86 it holds retire_lat, on powerpc it holds p_stage_cyc. platform-dependent queen 🌈
  • cpumode — the cpumode from the struct perf_event_header misc variable, masked with CPUMODE_MASK. gives you user, kernel and hypervisor information. the full trio ✨
  • no_hw_idx — for PERF_SAMPLE_BRANCH_STACK, this is true when PERF_SAMPLE_BRANCH_HW_INDEX isn't set.
  • deferred_callchain — when processing PERF_SAMPLE_CALLCHAIN, a deferred user callchain marker was encountered.
  • merged_callchain — a synthesized merged callchain that is allocated and needs freeing. 🗑️ yes, you gotta free her, don't leave her hanging.
  • deferred_cookie — identifier of the deferred callchain in the later PERF_RECORD_CALLCHAIN_DEFERRED event. a little cookie that tells you which one is which 🍪
  • insn — a copy of the sampled instruction, filled in by perf_sample__fetch_insn.
  • raw_data — pointer into the original event for PERF_SAMPLE_RAW data.
  • callchain — pointer into the original event for PERF_SAMPLE_CALLCHAIN data. ⚠️ for deferred callchains this may be a copy that needs freeing — see sample__merge_deferred_callchain. don't leak her, bestie 😭
  • branch_stack — pointer into the original event for PERF_SAMPLE_BRANCH_STACK data.
  • branch_stack_cntr — pointer into the original event for PERF_SAMPLE_BRANCH_COUNTERS data.
  • user_regs — values and pointers into the sample for PERF_SAMPLE_REGS_USER.
  • intr_regs — values and pointers into the sample for PERF_SAMPLE_REGS_INTR.
  • user_stack — size and pointer into the sample for PERF_SAMPLE_STACK_USER.
  • read — the sample event PERF_SAMPLE_READ counter values. the valid values depend on the attr.read_format PERF_FORMAT_ values. so like, read the format, girlies 📖
  • aux_sample — similar to raw data but with a 64-bit size and alignment, PERF_SAMPLE_AUX data. the deluxe version 💅
  • simd_flags — SIMD flag information from ARM SPE auxiliary events.

🔥 Description 🔥

so here's the tea, bestie ☕

a sample is generally filled in by evlist__parse_sample/evsel__parse_sample, which fills in the variables from a "union perf_event *event" — and that event is data from a perf ring buffer or a perf.data file. fr fr.

the "event" sample is variable in length, as determined by the perf_event_attr (in the evsel) plus details within the sample event itself. and that's literally why struct perf_sample exists: so you don't have to care about the variable-length nature of the original event. it's giving "I'll handle the chaos, you just read the fields" 🧚

to avoid being excessively large, parts of struct perf_sample are pointers into the original sample event. so heads up: in general, the lifetime of a struct perf_sample needs to be less than the "union perf_event *event" it was derived from. > ⚠️ like, do not let your struct outlive its source event, that's undefined-adjacent heartbreak 💀

the struct regs_dump user_regs and intr_regs are lazily allocated — again for size reasons — because they hold a cache of looked-up registers. the function pair perf_sample__init and perf_sample__exit correctly initialize and clean up these values. so like, use the pair. that's the whole vibe check ✅

👀 SEE ALSO 👀

  • Kernel file ./tools/perf/util/sample.h — go read it, it's right there 🌟

and that's the page, bestie 💜 go forth and sample responsibly ✨

cute little sign-off: this one lives at ./tools/perf/util, dated October 2026 🎀 — and yes, the header said struct perf_sample(9) and the footer said struct perf_sample(9) too, because consistency is iconic 👑

📦 where this page comes from