perf_event_open(2)
💖 perf_event_open(2) — System Calls Manual 💖
okay bestie, welcome to the perf_event_open manual page. it's giving performance monitoring, and we're about to go through it together. no cap. 💅
✨ NAME ✨
perf_event_open — set up performance monitoring 🌸
📚 LIBRARY 📚
Standard C library (libc, -lc) — yes, that's the whole thing. 💖
🛠️ SYNOPSIS 🛠️
#include <linux/perf_event.h> /* Definition of PERF_* constants */
#include <linux/hw_breakpoint.h> /* Definition of HW_* constants */
#include <sys/syscall.h> /* Definition of SYS_* constants */
#include <unistd.h>
int syscall(SYS_perf_event_open, struct perf_event_attr *attr,
pid_t pid, int cpu, int group_fd, unsigned long flags);Heads up bestie: glibc provides no wrapper forperf_event_open(), so you have to usesyscall(2). literally no other way. periodt. 💅
🌈 DESCRIPTION 🌈
Given a list of parameters, perf_event_open() returns a file descriptor, for use in subsequent system calls (read(2), mmap(2), prctl(2), fcntl(2), etc.). okay so you hand this syscall a list of parameters, and it hands you back a file descriptor. That fd is your new bestie for all the follow-up system calls you're gonna make: read(2), mmap(2), prctl(2), fcntl(2), etc. 💖
A call to perf_event_open() creates a file descriptor that allows measuring performance information. Each file descriptor corresponds to one event that is measured; these can be grouped together to measure multiple events simultaneously. slay. Every time you call perf_event_open(), you create a file descriptor that lets you measure performance info. Each fd is tied to one event being measured, and you can group them up to measure multiple events at the same time. no cap. ✨
Events can be enabled and disabled in two ways: via ioctl(2) and via prctl(2). When an event is disabled it does not count or generate overflows but does continue to exist and maintain its count value. You can enable and disable events in two ways: with ioctl(2) or with prctl(2). When an event is disabled, it does not count or generate overflows, but it still exists and keeps its count value. it's just chilling. 😌
Events come in two flavors: counting and sampled. A counting event is one that is used for counting the aggregate number of events that occur. In general, counting event results are gathered with a read(2) call. A sampling event periodically writes measurements to a buffer that can then be accessed via mmap(2). Events come in two flavors: counting and sampled. A counting event is all about counting the total number of events that happen. Usually you grab counting event results with a read(2) call. A sampling event periodically writes measurements into a buffer, and then you can access that buffer with mmap(2). main character energy fr fr. 💅
🌟 Arguments 🌟
The pid and cpu arguments allow specifying which process and CPU to monitor:
pid == 0andcpu == -1— This measures the calling process/thread on any CPU. 🦋pid == 0andcpu >= 0— This measures the calling process/thread only when running on the specified CPU. 🎀pid > 0andcpu == -1— This measures the specified process/thread on any CPU. ✨pid > 0andcpu >= 0— This measures the specified process/thread only when running on the specified CPU. 💖pid == -1andcpu >= 0— This measures all processes/threads on the specified CPU. This requiresCAP_PERFMON(since Linux 5.8) orCAP_SYS_ADMINcapability or a/proc/sys/kernel/perf_event_paranoidvalue of less than 1. 👑pid == -1andcpu == -1— This setting is invalid and will return an error. 💀
When pid is greater than zero, permission to perform this system call is governed by CAP_PERFMON (since Linux 5.9) and a ptrace access mode PTRACE_MODE_READ_REALCREDS check on older Linux versions; see ptrace(2). 🔐
The group_fd argument allows event groups to be created. An event group has one event which is the group leader. The leader is created first, with group_fd = -1. The rest of the group members are created with subsequent perf_event_open() calls with group_fd being set to the file descriptor of the group leader. (A single event on its own is created with group_fd = -1 and is considered to be a group with only 1 member.) An event group is scheduled onto the CPU as a unit: it will be put onto the CPU only if all of the events in the group can be put onto the CPU. This means that the values of the member events can be meaningfully compared —added, divided (to get ratios), and so on— with each other, since they have counted events for the same set of executed instructions. iykyk 💫
The flags argument is formed by ORing together zero or more of the following values:
PERF_FLAG_FD_CLOEXEC(since Linux 3.14) — This flag enables the close-on-exec flag for the created event file descriptor, so that the file descriptor is automatically closed onexecve(2). Setting the close-on-exec flags at creation time, rather than later withfcntl(2), avoids potential race conditions where the calling thread invokesperf_event_open()andfcntl(2)at the same time as another thread callsfork(2)thenexecve(2). 🧚PERF_FLAG_FD_NO_GROUP— This flag tells the event to ignore thegroup_fdparameter except for the purpose of setting up output redirection using thePERF_FLAG_FD_OUTPUTflag. 💜PERF_FLAG_FD_OUTPUT(broken since Linux 2.6.35) — This flag re-routes the event's sampled output to instead be included in the mmap buffer of the event specified bygroup_fd. 💀PERF_FLAG_PID_CGROUP(since Linux 2.6.39) — This flag activates per-container system-wide monitoring. A container is an abstraction that isolates a set of resources for finer-grained control (CPUs, memory, etc.). In this mode, the event is measured only if the thread running on the monitored CPU belongs to the designated container (cgroup). The cgroup is identified by passing a file descriptor opened on its directory in the cgroupfs filesystem. For instance, if the cgroup to monitor is calledtest, then a file descriptor opened on/dev/cgroup/test(assuming cgroupfs is mounted on/dev/cgroup) must be passed as thepidparameter. cgroup monitoring is available only for system-wide events and may therefore require extra permissions. 🫶
The perf_event_attr structure provides detailed configuration information for the event being created.
struct perf_event_attr {
__u32 type; /* Type of event */
__u32 size; /* Size of attribute structure */
__u64 config; /* Type-specific configuration */
union {
__u64 sample_period; /* Period of sampling */
__u64 sample_freq; /* Frequency of sampling */
};
__u64 sample_type; /* Specifies values included in sample */
__u64 read_format; /* Specifies values returned in read */
__u64 disabled : 1, /* off by default */
inherit : 1, /* children inherit it */
pinned : 1, /* must always be on PMU */
exclusive : 1, /* only group on PMU */
exclude_user : 1, /* don't count user */
exclude_kernel : 1, /* don't count kernel */
exclude_hv : 1, /* don't count hypervisor */
exclude_idle : 1, /* don't count when idle */
mmap : 1, /* include mmap data */
comm : 1, /* include comm data */
freq : 1, /* use freq, not period */
inherit_stat : 1, /* per task counts */
enable_on_exec : 1, /* next exec enables */
task : 1, /* trace fork/exit */
watermark : 1, /* wakeup_watermark */
precise_ip : 2, /* skid constraint */
mmap_data : 1, /* non-exec mmap data */
sample_id_all : 1, /* sample_type all events */
exclude_host : 1, /* don't count in host */
exclude_guest : 1, /* don't count in guest */
exclude_callchain_kernel : 1,
/* exclude kernel callchains */
exclude_callchain_user : 1,
/* exclude user callchains */
mmap2 : 1, /* include mmap with inode data */
comm_exec : 1, /* flag comm events that are
due to exec */
use_clockid : 1, /* use clockid for time fields */
context_switch : 1, /* context switch data */
write_backward : 1, /* Write ring buffer from end
to beginning */
namespaces : 1, /* include namespaces data */
ksymbol : 1, /* include ksymbol events */
bpf_event : 1, /* include bpf events */
aux_output : 1, /* generate AUX records
instead of events */
cgroup : 1, /* include cgroup events */
text_poke : 1, /* include text poke events */
build_id : 1, /* use build id in mmap2 events */
inherit_thread : 1, /* children only inherit */
/* if cloned with CLONE_THREAD */
remove_on_exec : 1, /* event is removed from task
on exec */
sigtrap : 1, /* send synchronous SIGTRAP
on event */
__reserved_1 : 26;
union {
__u32 wakeup_events; /* wakeup every n events */
__u32 wakeup_watermark; /* bytes before wakeup */
};
__u32 bp_type; /* breakpoint type */
union {
__u64 bp_addr; /* breakpoint address */
__u64 kprobe_func; /* for perf_kprobe */
__u64 uprobe_path; /* for perf_uprobe */
__u64 config1; /* extension of config */
};
union {
__u64 bp_len; /* breakpoint size */
__u64 kprobe_addr; /* with kprobe_func == NULL */
__u64 probe_offset; /* for perf_[k,u]probe */
__u64 config2; /* extension of config1 */
};
__u64 branch_sample_type; /* enum perf_branch_sample_type */
__u64 sample_regs_user; /* user regs to dump on samples */
__u32 sample_stack_user; /* size of stack to dump on
samples */
__s32 clockid; /* clock to use for time fields */
__u64 sample_regs_intr; /* regs to dump on samples */
__u32 aux_watermark; /* aux bytes before wakeup */
__u16 sample_max_stack; /* max frames in callchain */
__u16 __reserved_2; /* align to u64 */
__u32 aux_sample_size; /* max aux sample size */
__u32 __reserved_3; /* align to u64 */
__u64 sig_data; /* user data for sigtrap */
};The fields of the perf_event_attr structure are described in more detail below:
type — This field specifies the overall event type. It has one of the following values:
PERF_TYPE_HARDWARE— This indicates one of the "generalized" hardware events provided by the kernel. See theconfigfield definition for more details. ⭐PERF_TYPE_SOFTWARE— This indicates one of the software-defined events provided by the kernel (even if no hardware support is available). 🌈PERF_TYPE_TRACEPOINT— this one's saying "hey, we're vibing with a tracepoint from the kernel's tracepoint infrastructure, k?" 🧚PERF_TYPE_HW_CACHE— a hardware cache event, bestie. It's got its own lil special encoding situation going on, and it's all explained down in theconfigfield definition. 💅PERF_TYPE_RAW— ok so this is your "raw", implementation-specific event, and you shove it into theconfigfield. It's giving very much DIY energy. 🔥PERF_TYPE_BREAKPOINT(since Linux 2.6.33) — a hardware breakpoint, supplied by the CPU itself. These can be read/write accesses to an address, and they can also be execution of an instruction address. Iconic honestly. 👑- dynamic PMU — since Linux 2.6.38,
perf_event_open()can serve multiple PMUs and honestly, the way that it just manages them all? Obsessed. To turn this on, you use a value exported by the kernel in thetypefield to say which PMU you want. Where do you find that value, you ask? In thesysfsfilesystem — there's a subdirectory per PMU instance sitting under/sys/bus/event_source/devices. And in each one of those subdirectories there's atypefile whose content is an integer, and that integer is what you drop into thetypefield. For example,/sys/bus/event_source/devices/cpu/typeholds the value for the core CPU PMU, which is usually4. No cap. ✨ - kprobe, uprobe (both since Linux 4.17) — these two dynamic PMUs make a kprobe/uprobe and then attach it to the file descriptor that
perf_event_opengenerated. And here's the tea: the kprobe/uprobe gets destroyed when the file descriptor gets destroyed. So the two of them go down together, fr fr. See the fieldskprobe_func,uprobe_path,kprobe_addr, andprobe_offsetfor more deets. 🫶
size— the size of theperf_event_attrstructure, and it's there for forward/backward compatibility. Set it withsizeof(struct perf_event_attr)so the kernel can see the struct size as it was at the time of compilation. Yes, that's the move. 🎀
Now the related defines, and bestie, there's a whole timeline here:
PERF_ATTR_SIZE_VER0is set to64— this was the size of the very first published struct. The OG, the blueprint. 🌸PERF_ATTR_SIZE_VER1is72, corresponding to the addition of breakpoints in Linux 2.6.33.PERF_ATTR_SIZE_VER2is80, corresponding to the addition of branch sampling in Linux 3.4.PERF_ATTR_SIZE_VER3is96, corresponding to the addition ofsample_regs_userandsample_stack_userin Linux 3.7.PERF_ATTR_SIZE_VER4is104, corresponding to the addition ofsample_regs_intrin Linux 3.19.PERF_ATTR_SIZE_VER5is112, corresponding to the addition ofaux_watermarkin Linux 4.1. The glow-up is real. 💖
config— this is where you say which event you actually want, and it works together with thetypefield. Theconfig1andconfig2fields also get taken into account in the cases where 64 bits just isn't enough to fully specify the event (rude of the event, honestly). How these fields are encoded is event dependent. 🤷
There are several ways to set the config field, and which one you use depends on the value of the type field we just talked about. So here are the various possible settings for config, split up by type. Slay.
If type is PERF_TYPE_HARDWARE, we're measuring one of the generalized hardware CPU events. Not all of these are available on all platforms, so don't come for me if yours is missing. Set config to one of the following:
PERF_COUNT_HW_CPU_CYCLES— total cycles. Be wary of what happens during CPU frequency scaling, ok? Don't say I didn't warn you. 👀PERF_COUNT_HW_INSTRUCTIONS— retired instructions. Be careful, because these can be affected by various issues, most notably hardware interrupt counts.PERF_COUNT_HW_CACHE_REFERENCES— cache accesses. Usually this indicates Last Level Cache accesses, but this may vary depending on your CPU. It may also include prefetches and coherency messages; again, that depends on the design of your CPU. Very "it depends" of it. 🦋PERF_COUNT_HW_CACHE_MISSES— cache misses. Usually this means Last Level Cache misses, and it's intended to be used in conjunction with thePERF_COUNT_HW_CACHE_REFERENCESevent so you can calculate cache miss rates.PERF_COUNT_HW_BRANCH_INSTRUCTIONS— retired branch instructions. Prior to Linux 2.6.35, this used the wrong event on AMD processors. A lil historical oopsie. 💀PERF_COUNT_HW_BRANCH_MISSES— mispredicted branch instructions.PERF_COUNT_HW_BUS_CYCLES— bus cycles, which can be different from total cycles. Two different things, don't conflate them.PERF_COUNT_HW_STALLED_CYCLES_FRONTEND(since Linux 3.0) — stalled cycles during issue.PERF_COUNT_HW_STALLED_CYCLES_BACKEND(since Linux 3.0) — stalled cycles during retirement.PERF_COUNT_HW_REF_CPU_CYCLES(since Linux 3.3) — total cycles, and these are not affected by CPU frequency scaling. Finally, a cycle count that isn't out here shape-shifting on us. 💜
If type is PERF_TYPE_SOFTWARE, we're measuring software events provided by the kernel. Set config to one of these:
PERF_COUNT_SW_CPU_CLOCK— reports the CPU clock, which is a high-resolution per-CPU timer. ⌚PERF_COUNT_SW_TASK_CLOCK— reports a clock count specific to the task that's running.PERF_COUNT_SW_PAGE_FAULTS— reports the number of page faults.PERF_COUNT_SW_CONTEXT_SWITCHES— counts context switches. Until Linux 2.6.34, these were all reported as user-space events; after that, they're reported as happening in the kernel.PERF_COUNT_SW_CPU_MIGRATIONS— reports the number of times the process has migrated to a new CPU. Moving around, main character behavior. ✈️PERF_COUNT_SW_PAGE_FAULTS_MIN— counts the number of minor page faults. These did not require disk I/O to handle.PERF_COUNT_SW_PAGE_FAULTS_MAJ— counts the number of major page faults. These did require disk I/O to handle. Major, literally.PERF_COUNT_SW_ALIGNMENT_FAULTS(since Linux 2.6.33) — counts the number of alignment faults. These happen when unaligned memory accesses happen; the kernel can handle them, but it reduces performance. This only happens on some architectures (never on x86). So if you're on x86, not your problem, bestie. 💅PERF_COUNT_SW_EMULATION_FAULTS(since Linux 2.6.33) — counts the number of emulation faults. The kernel sometimes traps on unimplemented instructions and emulates them for user space. This can negatively impact performance, so… be aware. 😭PERF_COUNT_SW_DUMMY(since Linux 3.12) — a placeholder event that counts nothing. Informational sample record types likemmaporcommmust be associated with an active event, and this dummy event lets you gather those records without needing a counting event. It's giving "I'm just here for moral support". 🫶PERF_COUNT_SW_BPF_OUTPUT(since Linux 4.4) — used to generate raw sample data from BPF. BPF programs can write to this event using thebpf_perf_event_outputhelper.PERF_COUNT_SW_CGROUP_SWITCHES(since Linux 5.13) — counts context switches to a task in a different cgroup. In other words, if the next task is in the same cgroup, it won't count the switch. Same group = not counted, periodt. 👑
If type is PERF_TYPE_TRACEPOINT, then we're measuring kernel tracepoints. The value you use in config can be obtained from under debugfs at tracing/events/*/*/id if ftrace is enabled in the kernel.
If type is PERF_TYPE_HW_CACHE, then we're measuring a hardware CPU cache event. To calculate the appropriate config value, use this equation:
config = (perf_hw_cache_id) |
(perf_hw_cache_op_id << 8) |
(perf_hw_cache_op_result_id << 16);where perf_hw_cache_id is one of:
PERF_COUNT_HW_CACHE_L1D— for measuring Level 1 Data CachePERF_COUNT_HW_CACHE_L1I— for measuring Level 1 Instruction CachePERF_COUNT_HW_CACHE_LL— for measuring Last-Level CachePERF_COUNT_HW_CACHE_DTLB— for measuring the Data TLBPERF_COUNT_HW_CACHE_ITLB— for measuring the Instruction TLBPERF_COUNT_HW_CACHE_BPU— for measuring the branch prediction unitPERF_COUNT_HW_CACHE_NODE(since Linux 3.1) — for measuring local memory accesses
and perf_hw_cache_op_id is one of:
PERF_COUNT_HW_CACHE_OP_READ— for read accessesPERF_COUNT_HW_CACHE_OP_WRITE— for write accessesPERF_COUNT_HW_CACHE_OP_PREFETCH— for prefetch accesses
and perf_hw_cache_op_result_id is one of:
PERF_COUNT_HW_CACHE_RESULT_ACCESS— to measure accessesPERF_COUNT_HW_CACHE_RESULT_MISS— to measure misses
If type is PERF_TYPE_RAW, then you need a custom "raw" config value. Most CPUs support events that aren't covered by the "generalized" events. These are implementation defined, so go read your CPU manual (for example, the Intel Volume 3B documentation, or the AMD BIOS and Kernel Developer Guide). The libpfm4 library can be used to translate from the name in the architectural manuals to the raw hex value that perf_event_open() expects in this field. Very iykyk. 🧚
If type is PERF_TYPE_BREAKPOINT, then leave config set to zero. Its parameters are set in other places. Respect the system. ✨
If type is kprobe or uprobe, set retprobe (bit 0 of config, see /sys/bus/event_source/devices/[k,u]probe/format/retprobe) for kretprobe/uretprobe. See the fields kprobe_func, uprobe_path, kprobe_addr, and probe_offset for more details.
kprobe_func, uprobe_path, kprobe_addr, probe_offset
okay so these four bestie fields are literally describing the kprobe/uprobe for the dynamic PMUs kprobe and uprobe. here's the tea 🫖
- For kprobe: you use
kprobe_funcandprobe_offset, or you usekprobe_addrand leavekprobe_funcasNULL. - For uprobe: you use
uprobe_pathandprobe_offset.
that's it, that's the whole vibe. 💅
sample_period, sample_freq
A "sampling" event ✨ is one that pops off an overflow notification every N events, where N is whatever you put in sample_period. So like, a sampling event has sample_period > 0. When an overflow happens, the requested data gets recorded in the mmap buffer, and the sample_type field is the one that controls what data gets recorded on each overflow. 📝
sample_freq is your girl if you want to go by frequency instead of period — in that case you set the freq flag. The kernel will then adjust the sampling period to try and hit the rate you want. The rate of adjustment is a timer tick. ⏱️
sample_type
The various bits in this field specify which values get included in the sample. They get recorded in a ring-buffer, which user space can read using mmap(2). 🌀
Real talk: the order in which the values are saved in the sample is documented in the MMAP Layout subsection below — it is not the enum perf_event_sample_format order. no cap.
PERF_SAMPLE_IP — Records instruction pointer.
PERF_SAMPLE_TID — Records the process and thread IDs.
PERF_SAMPLE_TIME — Records a timestamp.
PERF_SAMPLE_ADDR — Records an address, if applicable.
PERF_SAMPLE_READ — Record counter values for all events in a group, not just the group leader. 👑
PERF_SAMPLE_CALLCHAIN — Records the callchain (stack backtrace).
PERF_SAMPLE_ID — Records a unique ID for the opened event's group leader.
PERF_SAMPLE_CPU — Records CPU number.
PERF_SAMPLE_PERIOD — Records the current sampling period.
PERF_SAMPLE_STREAM_ID — Records a unique ID for the opened event. Unlike PERF_SAMPLE_ID, the actual ID is returned, not the group leader. This ID is the same as the one returned by PERF_FORMAT_ID.
PERF_SAMPLE_RAW — Records additional data, if applicable. Usually returned by tracepoint events.
PERF_SAMPLE_BRANCH_STACK (since Linux 3.4) — This one gives you a record of recent branches, as provided by CPU branch sampling hardware (such as Intel Last Branch Record). Heads up tho: not all hardware supports this feature. 😭
Wanna filter which branches get reported? See the branch_sample_type field for how. 🔍
PERF_SAMPLE_REGS_USER (since Linux 3.7) — Records the current user-level CPU register state (the values in the process before the kernel was called).
PERF_SAMPLE_STACK_USER (since Linux 3.7) — Records the user level stack, which allows stack unwinding. 🧵
PERF_SAMPLE_WEIGHT (since Linux 3.10) — Records a hardware provided weight value that expresses how costly the sampled event was. This lets the hardware highlight expensive events in a profile. 💸
PERF_SAMPLE_DATA_SRC (since Linux 3.10) — Records the data source: where in the memory hierarchy the data associated with the sampled instruction came from. Only available if the underlying hardware actually supports this feature, bestie. 🙈
PERF_SAMPLE_IDENTIFIER (since Linux 3.12) — Places the SAMPLE_ID value in a fixed position in the record, either at the beginning (for sample events) or at the end (if a non-sample event). 📌
This was necessary because a sample stream may have records from various different event sources with different sample_type settings. Parsing the event stream properly was literally not possible, because you needed the format of the record to find SAMPLE_ID, but you couldn't find the format without knowing what event the sample belonged to — causing a circular dependency. 💀 absolute chaos.
The PERF_SAMPLE_IDENTIFIER setting makes the event stream always parsable by putting SAMPLE_ID in a fixed location, even though it means having duplicate SAMPLE_ID values in records. small price to pay, honestly.
PERF_SAMPLE_TRANSACTION (since Linux 3.13) — Records reasons for transactional memory abort events (for example, from Intel TSX transactional memory support).
⚠️ The precise_ip setting must be greater than 0 and a transactional memory abort event must be measured, otherwise no values will be recorded. Also note that some perf_event measurements, such as sampled cycle counting, may cause extraneous aborts — by causing an interrupt during a transaction. messy. 😬
PERF_SAMPLE_REGS_INTR (since Linux 3.19) — Records a subset of the current CPU register state as specified by sample_regs_intr. Unlike PERF_SAMPLE_REGS_USER, the register values will return kernel register state if the overflow happened while kernel code is running. And if the CPU supports hardware sampling of register state (i.e., PEBS on Intel x86) and precise_ip is set higher than zero, then the register values returned are those captured by hardware at the time of the sampled instruction's retirement. fancy. 🌟
PERF_SAMPLE_PHYS_ADDR (since Linux 4.13) — Records physical address of data like in PERF_SAMPLE_ADDR.
PERF_SAMPLE_CGROUP (since Linux 5.7) — Records the (perf_event) cgroup ID of the process. This corresponds to the id field in the PERF_RECORD_CGROUP event.
PERF_SAMPLE_DATA_PAGE_SIZE (since Linux 5.11) — Records page size of data like in PERF_SAMPLE_ADDR.
PERF_SAMPLE_CODE_PAGE_SIZE (since Linux 5.11) — Records page size of ip like in PERF_SAMPLE_IP.
PERF_SAMPLE_WEIGHT_STRUCT (since Linux 5.12) — Records hardware provided weight values like in PERF_SAMPLE_WEIGHT, but it can represent multiple values in a struct. This shares the same space as PERF_SAMPLE_WEIGHT, so you can apply either of those — not both. It has the following format, and the meaning of each field is dependent on the hardware implementation. 🛠️
union perf_sample_weight {
u64 full; /* PERF_SAMPLE_WEIGHT */
struct { /* PERF_SAMPLE_WEIGHT_STRUCT */
u32 var1_dw;
u16 var2_w;
u16 var3_w;
};
};read_format
This field specifies the format of the data returned by read(2) on a perf_event_open() file descriptor. 📖
PERF_FORMAT_TOTAL_TIME_ENABLED — Adds the 64-bit time_enabled field. This can be used to calculate estimated totals if the PMU is overcommitted and multiplexing is happening.
PERF_FORMAT_TOTAL_TIME_RUNNING — Adds the 64-bit time_running field. This can be used to calculate estimated totals if the PMU is overcommitted and multiplexing is happening.
PERF_FORMAT_ID — Adds a 64-bit unique value that corresponds to the event group.
PERF_FORMAT_GROUP — Allows all counter values in an event group to be read with one read. one read. that's the dream. 😌
PERF_FORMAT_LOST (since Linux 6.0) — Adds a 64-bit value that is the number of lost samples for this event. This would be only meaningful when sample_period or sample_freq is set.
disabled
The disabled bit specifies whether the counter starts out disabled or enabled. If it's disabled, the event can later be enabled by ioctl(2), prctl(2), or enable_on_exec. 🔛
When you're creating an event group, typically the group leader is initialized with disabled set to 1 and any child events are initialized with disabled set to 0. And here's the lil plot twist: despite disabled being 0, the child events will not start until the group leader is enabled. the group leader is such a main character. 👑
inherit
The inherit bit specifies that this counter should count events of child tasks as well as the task specified. ⚠️ This applies only to new children, not to any existing children at the time the counter is created (nor to any new children of existing children).
And ngl, inherit does not work for some combinations of read_format values, such as PERF_FORMAT_GROUP. Additionally, using it together with cpu == -1 prevents the creation of the mmap ring-buffer used for logging asynchronous events in sampled mode. so... yeah, watch out for that. 🙈
pinned
The pinned bit specifies that the counter should always be on the CPU if at all possible. It applies only to hardware counters and only to group leaders. 💅
If a pinned counter cannot be put onto the CPU (e.g., because there aren't enough hardware counters, or because of a conflict with some other event), then the counter goes into an 'error' state, where reads return end-of-file (i.e., read(2) returns 0) until the counter is subsequently enabled or disabled. it's giving "not my fault I'm just built different." 💀
exclusive
The exclusive bit specifies that when this counter's group is on the CPU, it should be the only group using the CPU's counters. In the future this may allow monitoring programs to support PMU features that need to run alone, so that they don't disrupt other hardware counters. ✨
Note that many unexpected situations may prevent events with the exclusive bit set from ever running. This includes any users running a system-wide measurement as well as any kernel use of the performance counters (including the commonly enabled NMI Watchdog Timer interface). 😭 so close yet so far.
exclude_user
If this bit is set, the count excludes events that happen in user space. 🚫
exclude_kernel
If this bit is set, the count excludes events that happen in kernel space. 🚫
okay bestie we're DEEP in the perf_event_attr flags now and this is where it gets ✨juicy✨ so lock in 💖
exclude_hv— set this bit and the count skips anything happening in the hypervisor. This one's mostly for PMUs that ship with built-in support for it (like POWER, iconic behavior honestly). On basically every other machine you'd need extra support to measure hypervisor stuff, so don't @ me.exclude_idle— set it and nothing gets counted while the CPU is running the idle task. You can currently enable this for any event type, but lowkey it gets ignored for everything except software events. 💀mmap— this bit turns onPERF_RECORD_MMAPsamples for everymmap(2)call that hasPROT_EXECset. Why do we care? Because it lets tools notice when new executable code gets mapped into a program (dynamic shared libraries, for example 🌸) so those addresses can be mapped back to the original code. it's giving observability.comm— enables tracking of the process command name as changed byexecve(2)andprctl(PR_SET_NAME), plus writes to/proc/self/comm. If thecomm_execflag also got set successfully (possible since Linux 3.16 ✨) then the misc flagPERF_RECORD_MISC_COMM_EXEClets you tell theexecve(2)case apart from all the others. no cap, that distinction slaps.freq— if this bit is set, thensample_frequencyis used when setting up the sampling interval, notsample_period. read that again bestie, it matters 🫶inherit_stat— this bit enables saving event counts on context switch for inherited tasks. It's only meaningful if theinheritfield is also set. (yes, ONLY then 🙈)enable_on_exec— set this and the counter automatically gets enabled after a call toexecve(2). cute, convenient, automatic 💅task— set it and fork/exit notifications get included in the ring buffer. 🎀watermark— if set, an overflow notification happens when we cross thewakeup_watermarkboundary. If NOT set, overflow notifications happen afterwakeup_eventssamples instead. pick your fighter.precise_ip(since Linux 2.6.35) — this controls the amount of skid. Now what is skid, you ask? It's how many instructions execute between an event of interest happening and the kernel being able to stop and record the event. Smaller skid is better and lets you report more accurately which events correspond to which instructions, but the hardware is often limited on how small this can actually go. 😭
The possible values of this field are:
- 0 —
SAMPLE_IPcan have arbitrary skid. - 1 —
SAMPLE_IPmust have constant skid. - 2 —
SAMPLE_IPrequested to have 0 skid. - 3 —
SAMPLE_IPmust have 0 skid. Also see the description ofPERF_RECORD_MISC_EXACT_IP.
mmap_data(since Linux 2.6.36) — the counterpart to themmapfield 💜. This enables generation ofPERF_RECORD_MMAPsamples formmap(2)calls that do not havePROT_EXECset (data and SysV shared memory, for example).sample_id_all(since Linux 2.6.38) — if set, thenTID,TIME,ID,STREAM_ID, andCPUcan additionally be included in non-PERF_RECORD_SAMPLEs, as long as the correspondingsample_typeis selected. 🦋
If PERF_SAMPLE_IDENTIFIER is specified, then an extra ID value gets included as the very last value to make parsing the record stream easier. Heads up: this may lead to the id value appearing twice. not a bug, it's a feature, iykyk.
The layout is described by this pseudo-structure:
struct sample_id {
{ u32 pid, tid; } /* if PERF_SAMPLE_TID set */
{ u64 time; } /* if PERF_SAMPLE_TIME set */
{ u64 id; } /* if PERF_SAMPLE_ID set */
{ u64 stream_id;} /* if PERF_SAMPLE_STREAM_ID set */
{ u32 cpu, res; } /* if PERF_SAMPLE_CPU set */
{ u64 id; } /* if PERF_SAMPLE_IDENTIFIER set */
};exclude_host(since Linux 3.2) — when you're measuring things that include processes running VM instances (i.e., processes that have executed aKVM_RUNioctl(2)), this measures only events happening inside a guest instance. Important caveat bestie: this is only meaningful outside the guests — it does not change counts gathered inside of a guest. Currently this is x86 only. ✨exclude_guest(since Linux 3.2) — same setup as above (processes running VM instances, i.e., they've executed aKVM_RUNioctl(2)), except this one does not measure events happening inside guest instances. Same caveat: only meaningful outside the guests, it doesn't change counts gathered inside of a guest. Also currently x86 only. 🔥exclude_callchain_kernel(since Linux 3.7) — do not include kernel callchains. bye 👋exclude_callchain_user(since Linux 3.7) — do not include user callchains. bye x2 👋mmap2(since Linux 3.16) — generates an extended executable mmap record that carries enough extra info to uniquely identify shared mappings. Themmapflag also has to be set for this to work, so don't forget it 🎀comm_exec(since Linux 3.16) — purely a feature-detection flag, it does not change kernel behavior. Here's the tea: if this flag can successfully be set, then, whencommis enabled, thePERF_RECORD_MISC_COMM_EXECflag gets set in the misc field of a comm record header whenever the rename event being reported was caused by a call toexecve(2). That lets tools tell the various types of process renaming apart. 👑use_clockid(since Linux 4.1) — lets you select which internal Linux clock to use when generating timestamps, via theclockidfield. This can make it way easier to correlate perf sample times with timestamps generated by other tools. matching vibes 💅context_switch(since Linux 4.3) — enables generation ofPERF_RECORD_SWITCHrecords when a context switch occurs. It also enables generation ofPERF_RECORD_SWITCH_CPU_WIDErecords when sampling in CPU-wide mode. This is in addition to the existing tracepoint and software events for measuring context switches. The flex of this method? It gives full information even with strictperf_event_paranoidsettings. periodt. 🌈write_backward(since Linux 4.6) — makes the ring buffer get written from the end to the beginning. This is to support reading from an overwritable ring buffer. 🧚namespaces(since Linux 4.11) — enables generation ofPERF_RECORD_NAMESPACESrecords when a task enters a new namespace. Each namespace has a combination of device and inode numbers. ⭐ksymbol(since Linux 5.0) — enables generation ofPERF_RECORD_KSYMBOLrecords when new kernel symbols get registered or unregistered. This is for analyzing dynamic kernel functions like eBPF. 🔥bpf_event(since Linux 5.0) — enables generation ofPERF_RECORD_BPF_EVENTrecords when an eBPF program is loaded or unloaded. 🦋aux_output(since Linux 5.4) — lets normal (non-AUX) events generate data for AUX events, if the hardware supports it. 💖cgroup(since Linux 5.7) — enables generation ofPERF_RECORD_CGROUPrecords when a new cgroup is created (and activated). 🎀text_poke(since Linux 5.8) — enables generation ofPERF_RECORD_TEXT_POKErecords when there's a change to the kernel text (i.e., self-modifying code). spooky but valid 👀build_id(since Linux 5.12) — changes the contents ofPERF_RECORD_MMAP2so it has a build-id instead of device and inode numbers. 💅inherit_thread(since Linux 5.13) — this disables inheritance of the event to a child process. Only new threads in the same process (which is cloned withCLONE_THREAD) will inherit the event. 🧵remove_on_exec(since Linux 5.13) — closes the event when it starts a new process image viaexecve(2). ✂️sigtrap(since Linux 5.13) — enables synchronous signal delivery ofSIGTRAPon event overflow. 🚨wakeup_eventswakeup_watermark— this union sets how many samples (wakeup_events) or bytes (wakeup_watermark) happen before an overflow notification happens. Which one gets used is selected by thewatermarkbit flag. 💧
wakeup_events counts only PERF_RECORD_SAMPLE record types. If you want an overflow notification for all PERF_RECORD types, choose watermark and set wakeup_watermark to 1. 🫶
Historic tea: prior to Linux 3.0, setting wakeup_events to 0 resulted in no overflow notifications; more recent kernels treat 0 the same as 1. glow-up tbh.
bp_type(since Linux 2.6.33) — chooses the breakpoint type. It's one of:HW_BREAKPOINT_EMPTY— no breakpoint.HW_BREAKPOINT_R— count when we read the memory location.HW_BREAKPOINT_W— count when we write the memory location.HW_BREAKPOINT_RW— count when we read or write the memory location.HW_BREAKPOINT_X— count when we execute code at the memory location.
The values can be combined with a bitwise or, but — and this is a hard no 🚫 — combining HW_BREAKPOINT_R or HW_BREAKPOINT_W with HW_BREAKPOINT_X is not allowed.
bp_addr(since Linux 2.6.33) — the address of the breakpoint. For execution breakpoints, this is the memory address of the instruction of interest; for read and write breakpoints, it's the memory address of the memory location of interest. 📍config1(since Linux 2.6.39) —config1is for setting events that need an extra register or otherwise don't fit in the regularconfigfield. RawOFFCORE_EVENTSon Nehalem/Westmere/SandyBridge use this field on Linux 3.3 and later kernels. 🧠bp_len(since Linux 2.6.33) —bp_lenis the size of the breakpoint being measured whentypeisPERF_TYPE_BREAKPOINT. Options areHW_BREAKPOINT_LEN_1,HW_BREAKPOINT_LEN_2,HW_BREAKPOINT_LEN_4, andHW_BREAKPOINT_LEN_8. For an execution breakpoint, set this tosizeof(long). 📏config2(since Linux 2.6.39) —config2is a further extension of theconfig1field. ✨branch_sample_type(since Linux 3.4) — ifPERF_SAMPLE_BRANCH_STACKis enabled, then this specifies which branches to include in the branch record. 🌿
okay so the first part of that value is the privilege level, and it's built from a combo of one of the values listed right down here. If you don't set the privilege level yourself, the kernel just goes ahead and uses the event's own privilege level. And listen — the event privilege level and the branch privilege level do not have to match. They're independent, they're living their own lives, periodt. 💅
PERF_SAMPLE_BRANCH_USER— branch target is in user space. 🧚PERF_SAMPLE_BRANCH_KERNEL— branch target is in kernel space. 👑PERF_SAMPLE_BRANCH_HV— branch target is in the hypervisor. 🌀PERF_SAMPLE_BRANCH_PLM_ALL— the convenience queen ✨: it's just the three values above ORed together. Iconic shortcut behavior, no cap.
On top of the privilege value, you've also gotta set at least one or more of these bits. Not optional bestie, it's giving required:
PERF_SAMPLE_BRANCH_ANY— any branch type. Literally all of them. 🙌PERF_SAMPLE_BRANCH_ANY_CALL— any call branch (this includes direct calls, indirect calls, and far jumps).PERF_SAMPLE_BRANCH_IND_CALL— indirect calls.PERF_SAMPLE_BRANCH_CALL(since Linux 4.4) — direct calls.PERF_SAMPLE_BRANCH_ANY_RETURN— any return branch.PERF_SAMPLE_BRANCH_IND_JUMP(since Linux 4.2) — indirect jumps.PERF_SAMPLE_BRANCH_COND(since Linux 3.16) — conditional branches.PERF_SAMPLE_BRANCH_ABORT_TX(since Linux 3.11) — transactional memory aborts.PERF_SAMPLE_BRANCH_IN_TX(since Linux 3.11) — branch that's inside a transactional memory transaction.PERF_SAMPLE_BRANCH_NO_TX(since Linux 3.11) — branch that's not inside a transactional memory transaction.PERF_SAMPLE_BRANCH_CALL_STACK(since Linux 4.1) — the branch is part of a hardware-generated call stack. Heads up though: this needs hardware support, and rn that's only found on Intel x86 Haswell or newer. 🔥
sample_regs_user(since Linux 3.7) — a bit mask that defines the set of user CPU registers to dump on samples. The layout of that register mask is architecture-specific, and it's described in the kernel header filearch/ARCH/include/uapi/asm/perf_regs.h. So like, go read your arch's version, iykyk.sample_stack_user(since Linux 3.7) — sets the size of the user stack to dump, but only ifPERF_SAMPLE_STACK_USERis specified. 🫶clockid(since Linux 4.1) — ifuse_clockidis set, this field picks which internal Linux timer gets used for timestamps. The available timers live inlinux/time.h, and the ones currently supported areCLOCK_MONOTONIC,CLOCK_MONOTONIC_RAW,CLOCK_REALTIME,CLOCK_BOOTTIME, andCLOCK_TAI. pick your fave ⏰aux_watermark(since Linux 4.1) — says how much data is required before aPERF_RECORD_AUXsample gets triggered.sample_max_stack(since Linux 4.8) — whensample_typeincludesPERF_SAMPLE_CALLCHAIN, this field says how many stack frames to report when generating the callchain. 🌸aux_sample_size(since Linux 5.5) — when thePERF_SAMPLE_AUXflag is set, this specifies the desired size of AUX data. Lowkey important caveat: you can actually get smaller data than the size you specified. So don't come crying when it's not the exact number. 😭sig_data(since Linux 5.13) — this data gets copied over to the user's signal handler (throughsi_perfin thesiginfo_t) so you can tell which event triggered the signal. Extremely useful when you're like "who sent for me??" 💀
Reading results
Once a perf_event_open() file descriptor is open, you can read the event values straight off that file descriptor. Which values show up there is decided by the read_format field in the attr structure, set at open time. 🔍
If you try to read into a buffer that isn't big enough to hold the data, you get the error ENOSPC. Rude, but fair.
Here's the layout of the data you get back from a read:
- If
PERF_FORMAT_GROUPwas specified, so you can read all the events in a group at once:
struct read_format {
u64 nr; /* The number of events */
u64 time_enabled; /* if PERF_FORMAT_TOTAL_TIME_ENABLED */
u64 time_running; /* if PERF_FORMAT_TOTAL_TIME_RUNNING */
struct {
u64 value; /* The value of the event */
u64 id; /* if PERF_FORMAT_ID */
u64 lost; /* if PERF_FORMAT_LOST */
} values[nr];
};- If
PERF_FORMAT_GROUPwas not specified:
struct read_format {
u64 value; /* The value of the event */
u64 time_enabled; /* if PERF_FORMAT_TOTAL_TIME_ENABLED */
u64 time_running; /* if PERF_FORMAT_TOTAL_TIME_RUNNING */
u64 id; /* if PERF_FORMAT_ID */
u64 lost; /* if PERF_FORMAT_LOST */
};And here's the tea on each value you read:
nr— the number of events in this file descriptor. Only available ifPERF_FORMAT_GROUPwas specified.time_enabledtime_running— the total time the event was enabled, and the total time it was running. Normally these two are the same. Multiplexing kicks in when the number of events is more than the number of available PMU counter slots — in that case the events only run part of the time, and you can use thetime_enabledandtime_runningvalues to scale an estimated value for the count. Math girlies rise up 📐✨value— an unsigned 64-bit value holding the counter result.id— a globally unique value for this particular event. Only present ifPERF_FORMAT_IDwas specified inread_format.lost— the number of lost samples of this event. Only present ifPERF_FORMAT_LOSTwas specified inread_format. 🫠
MMAP layout
When you use perf_event_open() in sampled mode, asynchronous events (like counter overflow, or PROT_EXEC mmap tracking) get logged into a ring-buffer. That ring-buffer is created and accessed through mmap(2). 🎀
The mmap size should be 1+2^n pages, where the first page is a metadata page (struct perf_event_mmap_page) holding various bits of info, like where the ring-buffer head is at. 👑
Before Linux 2.6.39 there's a bug, and it means you must allocate an mmap ring buffer when sampling — even if you have zero plans to ever access it. Not a vibe, but that's history for you.
The structure of that first metadata mmap page goes like this:
struct perf_event_mmap_page {
__u32 version; /* version number of this structure */
__u32 compat_version; /* lowest version this is compat with */
__u32 lock; /* seqlock for synchronization */
__u32 index; /* hardware counter identifier */
__s64 offset; /* add to hardware counter value */
__u64 time_enabled; /* time event active */
__u64 time_running; /* time event on CPU */
union {
__u64 capabilities;
struct {
__u64 cap_usr_time / cap_usr_rdpmc / cap_bit0 : 1,
cap_bit0_is_deprecated : 1,
cap_user_rdpmc : 1,
cap_user_time : 1,
cap_user_time_zero : 1,
};
};
__u16 pmc_width;
__u16 time_shift;
__u32 time_mult;
__u64 time_offset;
__u64 __reserved[120]; /* Pad to 1 k */
__u64 data_head; /* head in the data section */
__u64 data_tail; /* user-space written tail */
__u64 data_offset; /* where the buffer starts */
__u64 data_size; /* data buffer size */
__u64 aux_head;
__u64 aux_tail;
__u64 aux_offset;
__u64 aux_size;
}The list below breaks down the fields in the perf_event_mmap_page structure in more detail:
version— version number of this structure.compat_version— the lowest version this is compatible with.lock— a seqlock for synchronization.index— a unique hardware counter identifier.offset— when you're usingrdpmcfor reads, you must add this offset value to the one returned byrdpmcto get the current total event count. Don't forget it, bestie, or your numbers are gonna be a whole lie. 🙈time_enabled— the time the event was active.time_running— the time the event was running.cap_usr_time/cap_usr_rdpmc/cap_bit0(since Linux 3.4) — okay so there was a genuine bug in howcap_usr_timeandcap_usr_rdpmcwere defined, from Linux 3.4 all the way to Linux 3.11. Both bits pointed at the same location, so it was straight-up impossible to tell whethercap_usr_timeorcap_usr_rdpmcwere actually set. 💀
Starting with Linux 3.12, these get renamed to cap_bit0, and you should use the cap_user_time and cap_user_rdpmc fields instead. Periodt.
cap_bit0_is_deprecated(since Linux 3.12) — if this bit is set, it means the kernel supports the properly separatedcap_user_timeandcap_user_rdpmcbits. 🎉
If it's not set, that means you're on an older kernel where cap_usr_time and cap_usr_rdpmc map to the same bit, so both features should be used with caution. Ma'am, be careful.
cap_user_rdpmc(since Linux 3.12) — if the hardware supports reading performance counters from user space without a syscall (that's the "rdpmc" instruction on x86), then you can use the following code to do a read:
u32 seq, time_mult, time_shift, idx, width;
u64 count, enabled, running;
u64 cyc, time_offset;
do {
seq = pc->lock;
barrier();
enabled = pc->time_enabled;
running = pc->time_running;
if (pc->cap_usr_time && enabled != running) {
cyc = rdtsc();
time_offset = pc->time_offset;
time_mult = pc->time_mult;
time_shift = pc->time_shift;
}
idx = pc->index;
count = pc->offset;
if (pc->cap_usr_rdpmc && idx) {
width = pc->pmc_width;
count += rdpmc(idx - 1);
}
barrier();
} while (pc->lock != seq);cap_user_time(since Linux 3.12) — this bit means the hardware has a constant, nonstop timestamp counter (that's TSC on x86). ⭐cap_user_time_zero(since Linux 3.12) — indicates the presence oftime_zero, which lets you map timestamp values onto the hardware clock.pmc_width— ifcap_usr_rdpmcis set, this field gives you the bit-width of the value read using therdpmcor equivalent instruction. You can use this to sign extend the result, like:
...and for the individual counters that come back all squished into fewer than 64 bits, you do the little shift dance to sign-extend them back out 💅
pmc <<= 64 - pmc_width;
pmc >>= 64 - pmc_width; // signed shift right
count += pmc;time_shift, time_mult, time_offset
If cap_usr_time is set, these three are your besties for computing the time delta since time_enabled (in nanoseconds) using rdtsc or something like it 🕐
u64 quot, rem;
u64 delta;
quot = cyc >> time_shift;
rem = cyc & (((u64)1 << time_shift) - 1);
delta = time_offset + quot * time_mult +
((rem * time_mult) >> time_shift);Where time_offset, time_mult, time_shift, and cyc are read inside the seqcount loop we talked about up above. Then you can add this delta to enabled, and — if there's an idx — to running too, and the scaling gets so much better:
enabled += delta;
if (idx)
running += delta;
quot = count / running;
rem = count % running;
count = quot * enabled + (rem * enabled) / running;time_zero (since Linux 3.12)
If cap_usr_time_zero is set, then the hardware clock (that's the TSC timestamp counter on x86, iykyk) can be calculated from the time_zero, time_mult, and time_shift values 🌈
time = timestamp - time_zero;
quot = time / time_mult;
rem = time % time_mult;
cyc = (quot << time_shift) + (rem << time_shift) / time_mult;And the other way around, obviously:
quot = cyc >> time_shift;
rem = cyc & (((u64)1 << time_shift) - 1);
timestamp = time_zero + quot * time_mult +
((rem * time_mult) >> time_shift);data_head
This points to the head of the data section. The value just keeps increasing — it does not wrap. So you have to wrap it yourself, manually, by the size of the mmap buffer, before you go touching the samples. No cap.
On SMP-capable platforms, after reading the data_head value, user space should issue an rmb(). Don't skip that, bestie, it's important ✨
data_tail
When the mapping is PROT_WRITE, the data_tail value should be written by user space to reflect the last data that's been read. In that case, the kernel will not overwrite data you haven't read yet. Teamwork 💖
data_offset (since Linux 4.1)
Contains the offset of the location in the mmap buffer where the perf sample data begins.
data_size (since Linux 4.1)
Contains the size of the perf sample region within the mmap buffer.
aux_head, aux_tail, aux_offset, aux_size (since Linux 4.1)
The AUX region lets you mmap(2) a whole separate sample buffer for high-bandwidth data streams (separate from the main perf sample buffer, periodt). One example of a high-bandwidth stream is instruction tracing support, like you find in newer Intel processors 👑
To set up an AUX area, first aux_offset needs to be set with an offset greater than data_offset+data_size, and aux_size needs to be set to the buffer size you want. That offset and size have to be page aligned, and the size must be a power of two. Then you hand those values to mmap to actually map the AUX buffer. Pages in the AUX buffer count toward the RLIMIT_MEMLOCK resource limit (see setrlimit(2)), and also toward the perf_event_mlock_kb allowance.
By default, the AUX buffer will be truncated if it won't fit in the available space in the ring buffer. If the AUX buffer is mapped as a read-only buffer, then it operates in ring buffer mode, where old data gets overwritten by new. In overwrite mode it might not be possible to figure out where the new data began, and it is the consumer's job to disable measurement while reading, so you don't get yourself a data race 😭
The aux_head and aux_tail ring buffer pointers behave exactly the same, with the same ordering rules, as the data_head and data_tail we just described.
The following 2^n ring-buffer pages have the layout described below.
If perf_event_attr.sample_id_all is set, then all event types will have the sample_type selected fields that say where/when (identity) an event took place (TID, TIME, ID, CPU, STREAM_ID) — the ones described in PERF_RECORD_SAMPLE below — and it gets stashed just after the perf_event_header and after the fields already present for the existing fields, i.e. at the end of the payload. The whole point is that a newer perf.data file can be read by older perf tools, and those new optional fields just get ignored. Iconic backwards compat 💅
The mmap values start with a header:
struct perf_event_header {
__u32 type;
__u16 misc;
__u16 size;
};Below, we describe the perf_event_header fields in more detail. For ease of reading, the fields with shorter descriptions go first.
size
This indicates the size of the record.
misc
The misc field contains additional info about the sample.
You can figure out the CPU mode from this value by masking with PERF_RECORD_MISC_CPUMODE_MASK and looking for one of these (heads up: these are not bit masks, only one can be set at a time):
PERF_RECORD_MISC_CPUMODE_UNKNOWN— Unknown CPU mode.PERF_RECORD_MISC_KERNEL— Sample happened in the kernel.PERF_RECORD_MISC_USER— Sample happened in user code.PERF_RECORD_MISC_HYPERVISOR— Sample happened in the hypervisor.PERF_RECORD_MISC_GUEST_KERNEL(since Linux 2.6.35) — Sample happened in the guest kernel.PERF_RECORD_MISC_GUEST_USER(since Linux 2.6.35) — Sample happened in guest user code.
Since the following three statuses get generated by different record types, they alias to the same bit:
PERF_RECORD_MISC_MMAP_DATA(since Linux 3.10) — This is set when the mapping is not executable; otherwise the mapping is executable.PERF_RECORD_MISC_COMM_EXEC(since Linux 3.16) — This is set for aPERF_RECORD_COMMrecord on kernels more recent than Linux 3.16 if a process name change was caused by anexecve(2)system call.PERF_RECORD_MISC_SWITCH_OUT(since Linux 4.3) — When aPERF_RECORD_SWITCHorPERF_RECORD_SWITCH_CPU_WIDErecord is generated, this bit indicates that the context switch is away from the current process (instead of into the current process).
In addition, the following bits can be set:
PERF_RECORD_MISC_EXACT_IP— This indicates that the content ofPERF_SAMPLE_IPpoints to the actual instruction that triggered the event. See alsoperf_event_attr.precise_ip.PERF_RECORD_MISC_SWITCH_OUT_PREEMPT(since Linux 4.17) — When aPERF_RECORD_SWITCHorPERF_RECORD_SWITCH_CPU_WIDErecord is generated, this indicates the context switch was a preemption.PERF_RECORD_MISC_MMAP_BUILD_ID(since Linux 5.12) — This indicates that the content ofPERF_SAMPLE_MMAP2contains build-ID data instead of device major and minor numbers as well as the inode number.PERF_RECORD_MISC_EXT_RESERVED(since Linux 2.6.35) — This indicates there is extended data available (currently not used).PERF_RECORD_MISC_PROC_MAP_PARSE_TIMEOUT— This bit is not set by the kernel. It is reserved for the user-space perf utility, to indicate that/proc/pid/mapsparsing was taking too long and got stopped, and thus the mmap records may be truncated.
type
The type value is one of the ones below. The values in the corresponding record (the one that follows the header) depend on the type selected, as shown.
PERF_RECORD_MMAP
The MMAP events record the PROT_EXEC mappings so that we can correlate user-space IPs to code. They have this structure:
struct {
struct perf_event_header header;
u32 pid, tid;
u64 addr;
u64 len;
u64 pgoff;
char filename[];
};pidis the process ID.tidis the thread ID.addris the address of the allocated memory.lenis the size of the allocated memory.pgoffis the page offset of the allocated memory.filenameis a string describing the backing of the allocated memory.
PERF_RECORD_LOST
This record indicates when events are lost 😭
struct {
struct perf_event_header header;
u64 id;
u64 lost;
struct sample_id sample_id;
};idis the unique event ID for the samples that were lost.lostis the number of events that were lost.
PERF_RECORD_COMM
This record indicates a change in the process name.
struct {
struct perf_event_header header;
u32 pid;
u32 tid;
char comm[];
struct sample_id sample_id;
};pidis the process ID.tidis the thread ID.commis a string containing the new name of the process.
PERF_RECORD_EXIT
This record indicates a process exit event.
struct {
struct perf_event_header header;
u32 pid, ppid;
u32 tid, ptid;
u64 time;
struct sample_id sample_id;
};PERF_RECORD_THROTTLE, PERF_RECORD_UNTHROTTLE
This record indicates a throttle/unthrottle event.
struct {
struct perf_event_header header;
u64 time;
u64 id;
u64 stream_id;
struct sample_id sample_id;
};PERF_RECORD_FORK
This record indicates a fork event.
struct {
struct perf_event_header header;
u32 pid, ppid;
u32 tid, ptid;
u64 time;
struct sample_id sample_id;
};🎀 PERF_RECORD_READ
This record is literally just here to say "hey bestie, a read event happened" — that's the whole vibe. ✨
struct {
struct perf_event_header header;
u32 pid, tid;
struct read_format values;
struct sample_id sample_id;
};👑 PERF_RECORD_SAMPLE
Ok so THIS one is the main character of the whole record lineup — it indicates a sample. 📸
struct {
struct perf_event_header header;
u64 sample_id; /* if PERF_SAMPLE_IDENTIFIER */
u64 ip; /* if PERF_SAMPLE_IP */
u32 pid, tid; /* if PERF_SAMPLE_TID */
u64 time; /* if PERF_SAMPLE_TIME */
u64 addr; /* if PERF_SAMPLE_ADDR */
u64 id; /* if PERF_SAMPLE_ID */
u64 stream_id; /* if PERF_SAMPLE_STREAM_ID */
u32 cpu, res; /* if PERF_SAMPLE_CPU */
u64 period; /* if PERF_SAMPLE_PERIOD */
struct read_format v;
/* if PERF_SAMPLE_READ */
u64 nr; /* if PERF_SAMPLE_CALLCHAIN */
u64 ips[nr]; /* if PERF_SAMPLE_CALLCHAIN */
u32 size; /* if PERF_SAMPLE_RAW */
char data[size]; /* if PERF_SAMPLE_RAW */
u64 bnr; /* if PERF_SAMPLE_BRANCH_STACK */
struct perf_branch_entry lbr[bnr];
/* if PERF_SAMPLE_BRANCH_STACK */
u64 abi; /* if PERF_SAMPLE_REGS_USER */
u64 regs[weight(mask)];
/* if PERF_SAMPLE_REGS_USER */
u64 size; /* if PERF_SAMPLE_STACK_USER */
char data[size]; /* if PERF_SAMPLE_STACK_USER */
u64 dyn_size; /* if PERF_SAMPLE_STACK_USER &&
size != 0 */
union perf_sample_weight weight;
/* if PERF_SAMPLE_WEIGHT */
/* || PERF_SAMPLE_WEIGHT_STRUCT */
u64 data_src; /* if PERF_SAMPLE_DATA_SRC */
u64 transaction; /* if PERF_SAMPLE_TRANSACTION */
u64 abi; /* if PERF_SAMPLE_REGS_INTR */
u64 regs[weight(mask)];
/* if PERF_SAMPLE_REGS_INTR */
u64 phys_addr; /* if PERF_SAMPLE_PHYS_ADDR */
u64 cgroup; /* if PERF_SAMPLE_CGROUP */
u64 data_page_size;
/* if PERF_SAMPLE_DATA_PAGE_SIZE */
u64 code_page_size;
/* if PERF_SAMPLE_CODE_PAGE_SIZE */
u64 size; /* if PERF_SAMPLE_AUX */
char data[size]; /* if PERF_SAMPLE_AUX */
};And here's the field-by-field breakdown, because every single one of these is doing something 💅
sample_id— ifPERF_SAMPLE_IDENTIFIERis enabled, you get a 64-bit unique ID. It's a duplicate of thePERF_SAMPLE_IDid value, except it's parked at the beginning of the sample so parsers can snatch the value easily. 🫶ip— ifPERF_SAMPLE_IPis enabled, a 64-bit instruction pointer value is included. ✨pid,tid— ifPERF_SAMPLE_TIDis enabled, you get a 32-bit process ID and a 32-bit thread ID. 🌸time— ifPERF_SAMPLE_TIMEis enabled, a 64-bit timestamp is included. It's obtained vialocal_clock(), which is a hardware timestamp if one's available and thejiffiesvalue if it's not.addr— ifPERF_SAMPLE_ADDRis enabled, a 64-bit address is included. Usually it's the address of a tracepoint, breakpoint, or software event; otherwise the value is 0.id— ifPERF_SAMPLE_IDis enabled, a 64-bit unique ID is included. If the event is a member of an event group, the group leader ID is what comes back. This ID is the same as the one returned byPERF_FORMAT_ID.stream_id— ifPERF_SAMPLE_STREAM_IDis enabled, a 64-bit unique ID is included. UnlikePERF_SAMPLE_ID, the actual ID is returned here, not the group leader. This ID is the same as the one returned byPERF_FORMAT_ID.cpu,res— ifPERF_SAMPLE_CPUis enabled, this is a 32-bit value indicating which CPU was being used, plus a reserved (unused) 32-bit value. 🖥️period— ifPERF_SAMPLE_PERIODis enabled, a 64-bit value indicating the current sampling period is written.v— ifPERF_SAMPLE_READis enabled, a structure of typeread_formatis included which has values for all events in the event group. Which values show up? Depends on theread_formatvalue used atperf_event_open()time. iykyk.nr,ips[nr]— ifPERF_SAMPLE_CALLCHAINis enabled, a 64-bit number is included that says how many following 64-bit instruction pointers are coming. That's the current callchain. 🔥size,data[size]— ifPERF_SAMPLE_RAWis enabled, a 32-bit value indicatingsizeis included, followed by an array of 8-bit values,sizeof them. The values are padded with 0 to have 64-bit alignment.
This RAW record data is opaque with respect to the ABI. The ABI doesn't make any promises about the stability of its content — it may vary depending on event, hardware, and kernel version. 💀
bnr,lbr[bnr]— ifPERF_SAMPLE_BRANCH_STACKis enabled, a 64-bit value indicating the number of records is included, followed bybnrperf_branch_entrystructures which each include the fields:from— this indicates the source instruction (it may not be a branch).to— the branch target.mispred— the branch target was mispredicted.predicted— the branch target was predicted.in_tx(since Linux 3.11) — the branch was in a transactional memory transaction.abort(since Linux 3.11) — the branch was in an aborted transactional memory transaction.cycles(since Linux 4.3) — this reports the number of cycles elapsed since the previous branch stack update.
The entries go from most to least recent, so the first entry has the most recent branch. Support for mispred, predicted, and cycles is optional; if it's not supported, those values will be 0. The type of branches recorded is specified by the branch_sample_type field. 🌈
abi,regs[weight(mask)]— ifPERF_SAMPLE_REGS_USERis enabled, the user CPU registers get recorded. Theabifield is one ofPERF_SAMPLE_REGS_ABI_NONE,PERF_SAMPLE_REGS_ABI_32, orPERF_SAMPLE_REGS_ABI_64. Theregsfield is an array of the CPU registers that were specified by thesample_regs_userattr field — the number of values is the number of bits set in thesample_regs_userbit mask. ✨size,data[size],dyn_size— ifPERF_SAMPLE_STACK_USERis enabled, the user stack is recorded. You can use this to generate stack backtraces.sizeis the size requested by the user insample_stack_user, or else the maximum record size.datais the stack data (a raw dump of the memory pointed to by the stack pointer at the time of sampling).dyn_sizeis the amount of data actually dumped (it can be less thansize). Note thatdyn_sizeis omitted ifsizeis 0.weight— ifPERF_SAMPLE_WEIGHTorPERF_SAMPLE_WEIGHT_STRUCTis enabled, a 64-bit value provided by the hardware is recorded that indicates how costly the event was. This lets expensive events stand out way more clearly in profiles. 🔥data_src— ifPERF_SAMPLE_DATA_SRCis enabled, a 64-bit value is recorded that's made up of these fields:mem_op— type of opcode, a bitwise combination of:PERF_MEM_OP_NA— Not availablePERF_MEM_OP_LOAD— Load instructionPERF_MEM_OP_STORE— Store instructionPERF_MEM_OP_PFETCH— PrefetchPERF_MEM_OP_EXEC— Executable code
mem_lvl— memory hierarchy level hit or miss, a bitwise combination of the following, shifted left byPERF_MEM_LVL_SHIFT:
PERF_MEM_LVL_NA— not available, sorry bestie 😭PERF_MEM_LVL_HIT— hit ✨PERF_MEM_LVL_MISS— miss 💀PERF_MEM_LVL_L1— Level 1 cachePERF_MEM_LVL_LFB— line fill bufferPERF_MEM_LVL_L2— Level 2 cachePERF_MEM_LVL_L3— Level 3 cachePERF_MEM_LVL_LOC_RAM— local DRAMPERF_MEM_LVL_REM_RAM1— remote DRAM, 1 hopPERF_MEM_LVL_REM_RAM2— remote DRAM, 2 hopsPERF_MEM_LVL_REM_CCE1— remote cache, 1 hopPERF_MEM_LVL_REM_CCE2— remote cache, 2 hopsPERF_MEM_LVL_IO— I/O memoryPERF_MEM_LVL_UNC— uncached memory
🌸 mem_snoop
Snoop mode, cutie. It's a bitwise combination of the values below, all shifted left by PERF_MEM_SNOOP_SHIFT. Shifting?? yeah babes, that's the vibe:
PERF_MEM_SNOOP_NA— not availablePERF_MEM_SNOOP_NONE— no snoopPERF_MEM_SNOOP_HIT— snoop hitPERF_MEM_SNOOP_MISS— snoop missPERF_MEM_SNOOP_HITM— snoop hit modified
🔒 mem_lock
Lock instruction, bestie. Another bitwise combination of the following, shifted left by PERF_MEM_LOCK_SHIFT:
PERF_MEM_LOCK_NA— not availablePERF_MEM_LOCK_LOCKED— locked transaction 🔐
🧚 mem_dtlb
TLB access, hit or miss — a bitwise combination of the values below, shifted left by PERF_MEM_TLB_SHIFT:
PERF_MEM_TLB_NA— not availablePERF_MEM_TLB_HIT— hitPERF_MEM_TLB_MISS— missPERF_MEM_TLB_L1— Level 1 TLBPERF_MEM_TLB_L2— Level 2 TLBPERF_MEM_TLB_WK— hardware walkerPERF_MEM_TLB_OS— OS fault handler
💅 transaction
If the PERF_SAMPLE_TRANSACTION flag is set, then a 64-bit field gets recorded that describes where any transactional memory aborts came from. Very "here's the receipts" of it all.
The field is a bitwise combination of these values:
PERF_TXN_ELISION— abort from an elision type transaction (Intel-CPU-specific, iykyk).PERF_TXN_TRANSACTION— abort from a generic transaction.PERF_TXN_SYNC— synchronous abort (related to the reported instruction).PERF_TXN_ASYNC— asynchronous abort (not related to the reported instruction).PERF_TXN_RETRY— retryable abort (retrying the transaction may have succeeded 👀).PERF_TXN_CONFLICT— abort due to memory conflicts with other threads.PERF_TXN_CAPACITY_WRITE— abort due to write capacity overflow.PERF_TXN_CAPACITY_READ— abort due to read capacity overflow.
Plus, there's a user-specified abort code you can pull out of the high 32 bits of the field: shift right by PERF_TXN_ABORT_SHIFT and mask with the value PERF_TXN_ABORT_MASK. Chef's kiss extraction technique honestly 🫶
🦋 abi and regs[weight(mask)]
If PERF_SAMPLE_REGS_INTR is enabled, then the user CPU registers get recorded.
The abi field is one of PERF_SAMPLE_REGS_ABI_NONE, PERF_SAMPLE_REGS_ABI_32, or PERF_SAMPLE_REGS_ABI_64.
The regs field is an array of the CPU registers that were specified by the sample_regs_intr attr field. How many values? Exactly the number of bits set in the sample_regs_intr bit mask. Math girlie behavior 💖
⭐ phys_addr
If the PERF_SAMPLE_PHYS_ADDR flag is set, then the 64-bit physical address gets recorded.
🌈 cgroup
If the PERF_SAMPLE_CGROUP flag is set, then the 64-bit cgroup ID (for the perf_event subsystem) gets recorded. Wanna turn that into an actual pathname of the cgroup? The ID should match one in a PERF_RECORD_CGROUP.
🎀 data_page_size
If the PERF_SAMPLE_DATA_PAGE_SIZE flag is set, then the 64-bit page size value of the data address gets recorded.
✨ code_page_size
If the PERF_SAMPLE_CODE_PAGE_SIZE flag is set, then the 64-bit page size value of the ip address gets recorded.
🍓 size and data[size]
If PERF_SAMPLE_AUX is enabled, a snapshot of the aux buffer gets recorded. Snapshot!! 📸
👑 PERF_RECORD_MMAP2
This record is serving extended information on mmap(2) calls that return executable mappings. The format is similar to the PERF_RECORD_MMAP record, but it comes with extra values that let you uniquely identify shared mappings. Depending on the PERF_RECORD_MISC_MMAP_BUILD_ID bit in the header, those extra values have a different layout and different meanings. Two outfits, one record 💅
struct {
struct perf_event_header header;
u32 pid;
u32 tid;
u64 addr;
u64 len;
u64 pgoff;
union {
struct {
u32 maj;
u32 min;
u64 ino;
u64 ino_generation;
};
struct { /* if PERF_RECORD_MISC_MMAP_BUILD_ID */
u8 build_id_size;
u8 __reserved_1;
u16 __reserved_2;
u8 build_id[20];
};
};
u32 prot;
u32 flags;
char filename[];
struct sample_id sample_id;
};pid— is the process ID.tid— is the thread ID.addr— is the address of the allocated memory.len— is the size of the allocated memory.pgoff— is the page offset of the allocated memory.maj— is the major ID of the underlying device.min— is the minor ID of the underlying device.ino— is the inode number.ino_generation— is the inode generation.build_id_size— is the actual size of thebuild_idfield (up to 20).build_id— is a raw data to identify a binary.prot— is the protection information.flags— is the flags information.filename— is a string describing the backing of the allocated memory.
🌸 PERF_RECORD_AUX (since Linux 4.1)
This record reports that new data is available in the separate AUX buffer region. New data just dropped bestie 💖
struct {
struct perf_event_header header;
u64 aux_offset;
u64 aux_size;
u64 flags;
struct sample_id sample_id;
};aux_offset— offset in the AUX mmap region where the new data begins.aux_size— size of the data made available.flags— describes the AUX update.PERF_AUX_FLAG_TRUNCATED— if set, then the data returned was truncated to fit the available buffer size.PERF_AUX_FLAG_OVERWRITE— if set, then the data returned has overwritten previous data.
🧚 PERF_RECORD_ITRACE_START (since Linux 4.1)
This record indicates which process has initiated an instruction trace event, which lets tools properly correlate the instruction addresses in the AUX buffer with the proper executable. Matching game, but make it kernel 🙈
struct {
struct perf_event_header header;
u32 pid;
u32 tid;
};pid— process ID of the thread starting an instruction trace.tid— thread ID of the thread starting an instruction trace.
💀 PERF_RECORD_LOST_SAMPLES (since Linux 4.2)
When you're using hardware sampling (such as Intel PEBS), this record indicates some number of samples that may have been lost. Gone. Missing. Not me crying over dropped samples 😭
struct {
struct perf_event_header header;
u64 lost;
struct sample_id sample_id;
};lost— the number of potentially lost samples.
🔥 PERF_RECORD_SWITCH (since Linux 4.3)
This record indicates a context switch has happened. The PERF_RECORD_MISC_SWITCH_OUT bit in the misc field tells you whether it was a context switch into or away from the current process. Which way the plot twist goes, basically.
struct {
struct perf_event_header header;
struct sample_id sample_id;
};🌈 PERF_RECORD_SWITCH_CPU_WIDE (since Linux 4.3)
Same energy as PERF_RECORD_SWITCH — this record indicates a context switch has happened — but it only occurs when sampling in CPU-wide mode, and it serves extra info on the process being switched to/from. The PERF_RECORD_MISC_SWITCH_OUT bit in the misc field tells you whether it was a context switch into or away from the current process.
struct {
struct perf_event_header header;
u32 next_prev_pid;
u32 next_prev_tid;
struct sample_id sample_id;
};next_prev_pid— The process ID of the previous (if switching in) or next (if switching out) process on the CPU.next_prev_tid— the thread ID of the thread that was on this CPU before us (if we're switching in), or the thread that's about to hop on after us (if we're switching out). basic passing-the-baton behavior ✨
🫧 PERF_RECORD_NAMESPACES (since Linux 4.11)
bestie this record is literally a whole dossier of namespace info for a process. it's giving paperwork but make it iconic 💅
struct {
struct perf_event_header header;
u32 pid;
u32 tid;
u64 nr_namespaces;
struct { u64 dev, inode } [nr_namespaces];
struct sample_id sample_id;
};pid— the process ID 👑tid— the thread IDnr_namespace— how many namespaces are chillin' in this record
every single namespace comes with dev and inode fields and gets recorded in a fixed position, like assigned seating at a wedding, no switching 🎀
NET_NS_INDEX=0— Network namespace 🌐UTS_NS_INDEX=1— UTS namespaceIPC_NS_INDEX=2— IPC namespacePID_NS_INDEX=3— PID namespaceUSER_NS_INDEX=4— User namespaceMNT_NS_INDEX=5— Mount namespaceCGROUP_NS_INDEX=6— Cgroup namespace
🧚 PERF_RECORD_KSYMBOL (since Linux 5.0)
this record is the "hey bestie, a kernel symbol just showed up / dipped out" announcement 🦋
struct {
struct perf_event_header header;
u64 addr;
u32 len;
u16 ksym_type;
u16 flags;
char name[];
struct sample_id sample_id;
};addr— the address of the kernel symbollen— the size of the kernel symbolksym_type— the type of the kernel symbol. rn these are the available types:PERF_RECORD_KSYMBOL_TYPE_BPF— the kernel symbol is a BPF function 💜
flags— ifPERF_RECORD_KSYMBOL_FLAGS_UNREGISTERis set, then this event is about unregistering the kernel symbol, aka it's leaving the group chat 😭
🌸 PERF_RECORD_BPF_EVENT (since Linux 5.0)
this one right here tells you a BPF program got loaded or unloaded. main character energy each time, honestly ⭐
struct {
struct perf_event_header header;
u16 type;
u16 flags;
u32 id;
u8 tag[BPF_TAG_SIZE];
struct sample_id sample_id;
};type— one of these values, no cap:PERF_BPF_EVENT_PROG_LOAD— a BPF program got loaded ✨PERF_BPF_EVENT_PROG_UNLOAD— a BPF program got unloaded 💀
id— the ID of the BPF programtag— the tag of the BPF program. as of right now,BPF_TAG_SIZEis defined as8. periodt.
🎀 PERF_RECORD_CGROUP (since Linux 5.7)
a brand new cgroup just got created and activated, and this record is the ✨birth announcement✨
struct {
struct perf_event_header header;
u64 id;
char path[];
struct sample_id sample_id;
};id— the cgroup identifier. you can also grab this vianame_to_handle_at(2)on the cgroup path (as a file handle) 🫶path— the path of the cgroup, starting from the root
🔥 PERF_RECORD_TEXT_POKE (since Linux 5.8)
the kernel text said "new hair, who dis" — this record flags a change in the kernel text. this covers both adding and removing text, and when you're removing, the corresponding size is zero. keep that in mind bestie 🙈
struct {
struct perf_event_header header;
u64 addr;
u16 old_len;
u16 new_len;
u8 bytes[];
struct sample_id sample_id;
};addr— the address of the changeold_len— the old sizenew_len— the new sizebytes— contains the old bytes immediately followed by the new bytes
💖 Overflow handling
events can be set up so they ping you the moment a threshold gets crossed, which means an overflow happened. you can catch those overflow conditions by watching the event file descriptor with poll(2), select(2), or epoll(7) 👀 or, alternatively, you can catch overflow events through a signal handler with sa by enabling I/O signaling on the file descriptor — peep the discussion of the F_SETOWN and F_SETSIG operations in fcntl(2).
⚠️ overflows are generated only by sampling events. so sample_period has to have a nonzero value, mkay?
there are two ways to generate overflow notifications. let's get into it:
- The first way: set a
wakeup_eventsorwakeup_watermarkvalue that triggers once a certain number of samples (or bytes) have been written to the mmap ring buffer. when that happens,POLL_INis indicated. 🌈 - The other way: use the
PERF_EVENT_IOC_REFRESHioctl. this ioctl adds to a counter that decrements each time the event overflows. while it's nonzero,POLL_INis indicated — but the second the counter hits0,POLL_HUPis indicated and the underlying event gets disabled. (was that the plot twist? yes 🍓)
refreshing an event group leader refreshes all the siblings, and refreshing with a parameter of 0 currently enables infinite refreshes. heads up though: these behaviors are unsupported and you should not rely on them. not me telling you it's a trap 💀
starting with Linux 3.18, POLL_HUP is indicated if the event you're monitoring is attached to a different process and that process exits.
🧚 rdpmc instruction
starting with Linux 3.4 on x86, you can use the rdpmc instruction to get low-latency reads without ever entering the kernel. but ngl, using rdpmc is not necessarily faster than the other methods of reading event values. just so we're clear 🫶
you can detect support for this with the cap_usr_rdpmc field in the mmap page, and the documentation on how to calculate event values lives in that section. iykyk.
originally, when rdpmc support was enabled, any process (not just ones with an active perf event) could use the rdpmc instruction to access the counters. starting with Linux 4.0, rdpmc support is only allowed if an event is currently enabled in a process's context. want the old behavior back? write the value 2 to /sys/devices/cpu/rdpmc. iconic little hack, fr fr.
👑 perf_event ioctl calls
various ioctls act on perf_event_open() file descriptors — here's the whole lineup:
PERF_EVENT_IOC_ENABLE
this enables the individual event (or event group) specified by the file descriptor argument ✨
if the PERF_IOC_FLAG_GROUP bit is set in the ioctl argument, then all events in a group get enabled, even if the event you specified isn't the group leader (but see BUGS, bestie, always see BUGS).
PERF_EVENT_IOC_DISABLE
this disables the individual counter (or event group) specified by the file descriptor argument 🚫
enabling or disabling the leader of a group enables or disables the entire group — meaning while the group leader is disabled, none of the counters in the group will count. enabling or disabling a member of a group that isn't the leader affects only that one counter; disabling a non-leader stops that counter from counting but doesn't touch any other counter.
if the PERF_IOC_FLAG_GROUP bit is set in the ioctl argument, then all events in a group get disabled, even if the event you specified isn't the group leader (but see BUGS).
PERF_EVENT_IOC_REFRESH
non-inherited overflow counters can use this to enable a counter for a number of overflows specified by the argument, after which it gets disabled. subsequent calls to this ioctl add the argument value to the current count. an overflow notification with POLL_IN set will happen on each overflow until the count reaches 0 — when that happens, a notification with POLL_HUP set is sent and the event is disabled.
⚠️ passing an argument of 0 is considered undefined behavior. do not do it. that's not the vibe.
PERF_EVENT_IOC_RESET
resets the event count specified by the file descriptor argument to zero 🔄 this resets only the counts — there's literally no way to reset the multiplexing time_enabled or time_running values. they stay. they always stay.
if the PERF_IOC_FLAG_GROUP bit is set in the ioctl argument, then all events in a group get reset, even if the event you specified isn't the group leader (but see BUGS).
PERF_EVENT_IOC_PERIOD
this updates the overflow period for the event. ⏳
since Linux 3.7 (on ARM) and Linux 3.14 (all other architectures), the new period takes effect immediately. on older kernels, the new period didn't take effect until after the next overflow. boo, lag.
the argument is a pointer to a 64-bit value containing the desired new period.
⚠️ prior to Linux 2.6.36, this ioctl always failed due to a bug in the kernel. not our fault, it was a bug. 💀
PERF_EVENT_IOC_SET_OUTPUT
this tells the kernel to report event notifications to the specified file descriptor instead of the default one. the file descriptors must all be on the same CPU, no exceptions 🎯
the argument specifies the desired file descriptor, or -1 if output should be ignored.
PERF_EVENT_IOC_SET_FILTER (since Linux 2.6.33)
this adds an ftrace filter to this event 🦋
the argument is a pointer to the desired ftrace filter.
PERF_EVENT_IOC_ID (since Linux 3.12)
this returns the event ID value for the given event file descriptor 🏷️
the argument is a pointer to a 64-bit unsigned integer to hold the result.
PERF_EVENT_IOC_SET_BPF (since Linux 4.1)
this lets you attach a Berkeley Packet Filter (BPF) program to an existing kprobe tracepoint event. you need CAP_PERFMON (since Linux 5.8) or CAP_SYS_ADMIN privileges to use this ioctl 🔐
the argument is a BPF program file descriptor that was created by a previous bpf(2) system call.
PERF_EVENT_IOC_PAUSE_OUTPUT (since Linux 4.7)
this allows pausing and resuming the event's ring-buffer. and listen: a paused ring-buffer does not prevent generation of samples — it simply discards them. those discarded samples are considered lost, and cause a PERF_RECORD_LOST sample to be generated whenever possible. an overflow signal may still be triggered by the discarded sample even though the ring-buffer remains empty. messy behavior honestly 💅
- The argument is an unsigned 32-bit integer 💖 — a nonzero value pauses the ring-buffer, and a zero value resumes the ring-buffer. That's it, that's the whole vibe. Pause/resume, slay. ✨
PERF_EVENT_MODIFY_ATTRIBUTES (since Linux 4.17)
- Okay so this one lets you modify an event that already exists, without the whole dramatic overhead of closing it and reopening a brand-new one 😤. Currently it's only supported for breakpoint events, that's the limit bestie.
- The argument is a pointer to a
perf_event_attrstructure holding the updated event settings. 💅
PERF_EVENT_IOC_QUERY_BPF (since Linux 4.16)
- This lets you query which Berkeley Packet Filter (BPF) programs are attached to an existing kprobe tracepoint 🦋. Real talk: you can only attach one BPF program per event, but you can have multiple events attached to a tracepoint. Querying this value on one tracepoint event returns the ID of all BPF programs in all events attached to the tracepoint. You need
CAP_PERFMON(since Linux 5.8) orCAP_SYS_ADMINprivileges to use this ioctl, no cap. 🔐 - The argument is a pointer to a structure, and it looks like this:
struct perf_event_query_bpf {
__u32 ids_len;
__u32 prog_cnt;
__u32 ids[0];
};- So
ids_lentells the kernel how many ids can actually fit in theidsarray you handed over. The kernel fills inprog_cntwith the number of attached BPF programs. Theidsarray gets filled with the ID of each attached BPF program. And if there are more programs than will fit in the array, the kernel returnsENOSPCandids_lenwill tell you the number of program IDs that were successfully copied 😭. Noted, bestie.
🫶 Using prctl(2)
A process can enable or disable all currently open event groups using the prctl(2) PR_TASK_PERF_EVENTS_ENABLE and PR_TASK_PERF_EVENTS_DISABLE operations ✨.
Important caveats though, read the fine print:
- This applies only to events created locally by the calling process.
- It does not apply to events created by other processes attached to the calling process, or to inherited events from a parent process.
- Only group leaders are enabled and disabled — not any other members of the groups. 👑
📁 perf_event related configuration files
Files in /proc/sys/kernel/
/proc/sys/kernel/perf_event_paranoid— theperf_event_paranoidfile can be set to restrict access to the performance counters. The vibes, ranked:2— allow only user-space measurements (default since Linux 4.6).1— allow both kernel and user measurements (default before Linux 4.6).0— allow access to CPU-specific data but not raw tracepoint samples.-1— no restrictions. chaos mode 😈
The existence of the perf_event_paranoid file is the official method for determining if a kernel supports perf_event_open(). iykyk. 💅
/proc/sys/kernel/perf_event_max_sample_rate— this sets the maximum sample rate. Setting this too high can allow users to sample at a rate that impacts overall machine performance and potentially lock up the machine 💀. The default value is100000(samples per second). Do not test this on a machine you love./proc/sys/kernel/perf_event_max_stack— this file sets the maximum depth of stack frame entries reported when generating a call trace. 🥞/proc/sys/kernel/perf_event_mlock_kb— maximum number of pages an unprivileged user canmlock(2). The default is516(kB).
Files in /sys/bus/event_source/devices/
Since Linux 2.6.34, the kernel supports having multiple PMUs available for monitoring 🌈. Info on how to program these PMUs can be found under /sys/bus/event_source/devices/. Each subdirectory corresponds to a different PMU. It's giving organized.
/sys/bus/event_source/devices/*/type(since Linux 2.6.38) — this contains an integer that can be used in thetypefield ofperf_event_attrto indicate that you wish to use this PMU. 🎯/sys/bus/event_source/devices/cpu/rdpmc(since Linux 3.4) — if this file is1, then direct user-space access to the performance counter registers is allowed via therdpmcinstruction. This can be disabled by echoing0to the file.
As of Linux 4.0 the behavior has changed, so that 1 now means only allow access to processes with active perf events, with 2 indicating the old allow-anyone-access behavior. Behavior glow-up fr fr. ✨
/sys/bus/event_source/devices/*/format/(since Linux 3.4) — this subdirectory contains information on the architecture-specific subfields available for programming the variousconfigfields in theperf_event_attrstruct.
The content of each file is the name of the config field, followed by a colon, followed by a series of integer bit ranges separated by commas. For example, the file event may contain the value config1:1,6-10,44 which indicates that event is an attribute that occupies bits 1, 6–10, and 44 of perf_event_attr::config1. Copy that down bestie, character for character. 📝
/sys/bus/event_source/devices/*/events/(since Linux 3.4) — this subdirectory contains files with predefined events. The contents are strings describing the event settings expressed in terms of the fields found in the previously mentioned./format/directory. These are not necessarily complete lists of all events supported by a PMU, but usually a subset of events deemed useful or interesting. 🔥
The content of each file is a list of attribute names separated by commas. Each entry has an optional value (either hex or decimal). If no value is specified, then it is assumed to be a single-bit field with a value of 1. An example entry may look like this: event=0x2,inv,ldlat=3.
/sys/bus/event_source/devices/*/uevent— this file is the standard kernel device interface for injecting hotplug events. 🔌/sys/bus/event_source/devices/*/cpumask(since Linux 3.7) — thecpumaskfile contains a comma-separated list of integers that indicate a representative CPU number for each socket (package) on the motherboard. This is needed when setting up uncore or northbridge events, as those PMUs present socket-wide events. 👑
✨ RETURN VALUE ✨
On success, perf_event_open() returns the new file descriptor 🎀.
On error, -1 is returned and errno is set to indicate the error. That's the whole deal.
🔥 ERRORS 🔥
Heads up bestie: the errors returned by perf_event_open() can be inconsistent, and may vary across processor architectures and performance monitoring units. So don't come for me if your machine acts different, it's literally documented behavior. 🙈
E2BIG— Returned if theperf_event_attrsize value is too small (smaller thanPERF_ATTR_SIZE_VER0), too big (larger than the page size), or larger than the kernel supports and the extra bytes are not zero. WhenE2BIGis returned, theperf_event_attrsizefield is overwritten by the kernel to be the size of the structure it was expecting. Surprise, the kernel edited your struct.EACCES— Returned when the requested event requiresCAP_PERFMON(since Linux 5.8) orCAP_SYS_ADMINpermissions (or a more permissiveperf_eventparanoid setting). Some common cases where an unprivileged process may encounter this error: attaching to a process owned by a different user; monitoring all processes on a given CPU (i.e., specifying thepidargument as-1); and not settingexclude_kernelwhen the paranoid setting requires it. Read the room (and the paranoid file). 💀EBADF— Returned if thegroup_fdfile descriptor is not valid, or, ifPERF_FLAG_PID_CGROUPis set, the cgroup file descriptor inpidis not valid.EBUSY(since Linux 4.1) — Returned if another event already has exclusive access to the PMU. It's taken, back off. 😤EFAULT— Returned if theattrpointer points at an invalid memory address.EINTR— Returned when trying to mixperfandftracehandling for a uprobe.EINVAL— Returned if the specified event is invalid. There are many possible reasons for this. A not-exhaustive list:sample_freqis higher than the maximum setting; thecputo monitor does not exist;read_formatis out of range;sample_typeis out of range; theflagsvalue is out of range;exclusiveorpinnedset and the event is not a group leader; the eventconfigvalues are out of range or set reserved bits; the generic event selected is not supported; or there is not enough room to add the selected event. It's giving "something's wrong but I'm not saying which". 🙈EMFILE— Each opened event uses one file descriptor. If a large number of events are opened, the per-process limit on the number of open file descriptors will be reached, and no more events can be created. FD budget: spent. 😭ENODEV— Returned when the event involves a feature not supported by the current CPU.ENOENT— Returned if thetypesetting is not valid. This error is also returned for some unsupported generic events.ENOSPC— Prior to Linux 3.3, if there was not enough room for the event,ENOSPCwas returned. In Linux 3.3, this was changed toEINVAL.ENOSPCis still returned if you try to add more breakpoint events than supported by the hardware.ENOSYS— Returned ifPERF_SAMPLE_STACK_USERis set insample_typeand it is not supported by hardware.EOPNOTSUPP— Returned if an event requiring a specific hardware feature is requested but there is no hardware support. This includes requesting low-skid events if not supported, branch tracing if it is not available, sampling if no PMU interrupt is available, and branch stacks for software events. The hardware said no. 🤷♀️EOVERFLOW(since Linux 4.8) — Returned ifPERF_SAMPLE_CALLCHAINis requested andsample_max_stackis larger than the maximum specified in/proc/sys/kernel/perf_event_max_stack.EPERM— Returned on many (but not all) architectures when an unsupportedexclude_hv,exclude_idle,exclude_user, orexclude_kernelsetting is specified.
It can also happen, as with EACCES, when the requested event requires CAP_PERFMON (since Linux 5.8) or CAP_SYS_ADMIN permissions (or a more permissive perf_event paranoid setting). This includes setting a breakpoint on a kernel address, and (since Linux 3.13) setting a kernel function-trace tracepoint. 🚫
ESRCH— Returned if attempting to attach to a process that does not exist. Ghosted. 👻
📜 STANDARDS
Linux. That's the whole section, bestie. Periodt.
🦋 HISTORY
perf_event_open() was introduced in Linux 2.6.31 but was called perf_counter_open(). It was renamed in Linux 2.6.32. A little rebrand, we love a glow-up. ✨
💭 NOTES 💭
Okay bestie, so the official way to find out if perf_event_open() support is even turned on in your kernel is checking whether this file exists:
/proc/sys/kernel/perf_event_paranoid
That's it. That's the vibe check. If it's there, you're in business. ✨
Now, the CAP_PERFMON capability (living its best life since Linux 5.8) gives you a secure way to do performance monitoring and observability operations on a system — following the principal of least privilege (POSIX IEEE 1003.1e, she's fancy 💅).
The way that you use CAP_PERFMON instead of the much more powerful CAP_SYS_ADMIN for this? It excludes chances to misuse credentials and makes operations more secure, periodt. 🙅♀️
Real talk: usingCAP_SYS_ADMINfor secure system performance monitoring and observability is discouraged in favor of theCAP_PERFMONcapability. Don't do it, bestie. It's giving "I borrowed the whole master key when I just needed a room key" energy. 🔑
💀 BUGS 💀
Okay so here's where we get messy. Buckle up, this list is long and it's lowkey iconic. 🫠
- The
F_SETOWN_EXoption tofcntl(2)is needed to properly get overflow signals in threads. This was introduced in Linux 2.6.32. - Prior to Linux 2.6.33 (at least for x86), the kernel did not check if events could be scheduled together until read time. The same thing happens on all known kernels if the NMI watchdog is enabled. Which means: to see if a given set of events even works, you have to
perf_event_open(), start, then read — before you know for sure you can get valid measurements. 😭 - Prior to Linux 2.6.34, event constraints were not enforced by the kernel at all. In that case, some events would silently return "0" if the kernel scheduled them in an improper counter slot. Silent wrong answers?? Not the vibe. 🙈
- Prior to Linux 2.6.34, there was a bug when multiplexing where the wrong results could be returned. 💀
- Kernels from Linux 2.6.35 to Linux 2.6.39 can quickly crash the kernel if "inherit" is enabled and many threads are started. Crashing the whole kernel, no cap. 🔥
- Prior to Linux 2.6.35,
PERF_FORMAT_GROUPdid not work with attached processes. - There's a bug in the kernel code between Linux 2.6.36 and Linux 3.0 that ignores the "watermark" field and acts as if a
wakeup_eventwas chosen if the union has a nonzero value in it. - From Linux 2.6.31 to Linux 3.4, the
PERF_IOC_FLAG_GROUPioctl argument was broken and would repeatedly operate on the event specified rather than iterating across all sibling events in a group. - From Linux 3.4 to Linux 3.11, the mmap
cap_usr_rdpmcandcap_usr_timebits mapped to the same location. Code should migrate to the newcap_user_rdpmcandcap_user_timefields instead. (Glow-up required ✨) - Always double-check your results! Various generalized events have had wrong values. For example, retired branches measured the wrong thing on AMD machines until Linux 2.6.35. 👀
TL;DR of the whole BUGS section: trust, but verify. And definitely verify if you're on an ancient kernel, because bestie, some of these are rough. 🌸
🌈 EXAMPLES 🌈
Here's a short little baby example that measures the total instruction count of a call to printf(3). She's cute, she's simple, she slays. 💖
#include <err.h>
#include <linux/perf_event.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/ioctl.h>
#include <sys/syscall.h>
#include <sys/types.h>
#include <unistd.h>
static long
perf_event_open(struct perf_event_attr *hw_event, pid_t pid,
int cpu, int group_fd, unsigned long flags)
{
int ret;
ret = syscall(SYS_perf_event_open, hw_event, pid, cpu,
group_fd, flags);
return ret;
}
int
main(void)
{
int fd;
long long count;
struct perf_event_attr pe;
memset(&pe, 0, sizeof(pe));
pe.type = PERF_TYPE_HARDWARE;
pe.size = sizeof(pe);
pe.config = PERF_COUNT_HW_INSTRUCTIONS;
pe.disabled = 1;
pe.exclude_kernel = 1;
pe.exclude_hv = 1;
fd = perf_event_open(&pe, 0, -1, -1, 0);
if (fd == -1)
err(EXIT_FAILURE, "Error opening leader %llx\n", pe.config);
if (ioctl(fd, PERF_EVENT_IOC_RESET, 0) == -1)
err(EXIT_FAILURE, "PERF_EVENT_IOC_RESET");
if (ioctl(fd, PERF_EVENT_IOC_ENABLE, 0) == -1)
err(EXIT_FAILURE, "PERF_EVENT_IOC_ENABLE");
printf("Measuring instruction count for this printf\n");
if (ioctl(fd, PERF_EVENT_IOC_DISABLE, 0) == -1)
err(EXIT_FAILURE, "PERF_EVENT_IOC_DISABLE");
if (read(fd, &count, sizeof(count)) != sizeof(count))
err(EXIT_FAILURE, "read");
printf("Used %lld instructions\n", count);
if (close(fd) == -1)
err(EXIT_FAILURE, "close");
}Like… look at her go. Opening the event, resetting it, enabling it, running the printf, disabling it, reading the count, closing the fd. Chef's kiss 🎀
👀 SEE ALSO 👀
Go read these next, bestie, they're all connected:
perf(1)fcntl(2)mmap(2)open(2)prctl(2)read(2)Documentation/admin-guide/perf-security.rstin the kernel source tree
And that's the whole entire page, bestie!! 🎉✨💖 This one's from Linux man-pages 6.20, dated 2026-05-04, and it belongs to perf_event_open(2) — the icon, the moment, the legend. Go measure something. Responsibly. With CAP_PERFMON. Periodt. 💅🦋🌈⭐
📦 where this page comes from
- arch rolling: man-pages 6.20-1 · BSD-2-Clause AND BSD-3-Clause AND BSD-4.3TAHOE AND BSD-4-Clause-UC AND GPL-1.0-or-later AND GPL-2.0-only AND GPL-2.0-or-later AND GPL-3.0-or-later AND LGPL-3.0-linking-exception AND LGPL-3.0-or-later AND LicenseRef-Public-Domain AND LicenseRef-UltraPermissive AND Linux-man-pages-1-para AND Linux-man-pages-copyleft AND Linux-man-pages-copyleft-2-para AND Linux-man-pages-copyleft-var AND MIT AND Spencer-94
- nixpkgs unstable: man-pages 6.20
- 📜 the page's license: GPL-2.0-or-later
- Copyright 2012, Vincent Weaver <vincent.weaver@maine.edu>
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms