The `perf_event_open` System Call: Unlocking Deep CPU Telemetry

Standard profilers are often too blunt. When you’re chasing down a 1% latency regression in a high-frequency trading system or a database kernel, tools like perf give you a system-wide view, but what you really need is a scalpel to measure the instruction count of a single, critical function. This is where you drop down to the syscall level.

TL;DR: The perf_event_open system call is the Linux kernel’s fundamental API for accessing CPU hardware performance counters. It’s the engine under perf, eBPF, and other profilers. This post dissects its complex arguments, providing a flowchart and C code to help you build custom, ultra-low-overhead performance monitoring directly into your applications.

What you’ll walk away with:

• A mental model of how userspace tools access hardware performance counters.
• A decision flowchart for choosing the correct perf_event_attr parameters.
• A copy-pasteable C snippet to count CPU instructions for a specific thread.
• A clear understanding of when to use the raw syscall versus higher-level tools.

What is the perf_event_open system call?

The perf_event_open system call is the primary kernel interface for creating file descriptors that provide access to the Performance Monitoring Unit (PMU) on a CPU. It allows a program to count or sample hardware events (like CPU cycles and cache misses) and software events (like context switches and page faults) for a specific process or CPU.

This syscall is the foundation upon which nearly all modern Linux performance tooling is built. When you run perf stat -e cycles ./my_app, the perf tool is internally calling perf_event_open to create a counter for the cycles event, associating it with your application’s process ID, and then reading the final count from the resulting file descriptor when the process exits. Understanding this syscall means understanding how performance telemetry is fundamentally collected on Linux.

The core of its complexity lies in a single struct, perf_event_attr, which is passed to the kernel to configure the event you want to monitor. Getting this struct right is 90% of the battle.

For a deep dive into another powerful, low-level kernel technology, see eBPF Unleashed: The Future of Cloud-Native Observability.

The perf_event_open syscall is your entry point for building bespoke profiling tools when generic ones don’t provide enough granularity or control.

How do you choose the right parameters?

You configure a performance event by populating a perf_event_attr struct and passing its address to the syscall. The essential fields are type, which specifies the event category (e.g., hardware or software), and config, which selects the specific event (e.g., CPU cycles or page faults). Additional flags control behavior like inheritance across forks and sampling frequency.

The sheer number of options is intimidating. The flowchart below maps the most common monitoring goals to the required perf_event_attr settings and syscall arguments.

graph TD
    A[Start: "Need to profile?"] --> B{"Hardware or<br/>Software Event?"};
    B -- "Hardware" --> C{"What kind?"};
    C -- "CPU Cycles" --> D["type = PERF_TYPE_HARDWARE<br/>config = PERF_COUNT_HW_CPU_CYCLES"];
    C -- "Instructions" --> E["type = PERF_TYPE_HARDWARE<br/>config = PERF_COUNT_HW_INSTRUCTIONS"];
    C -- "Cache Misses" --> F["type = PERF_TYPE_HARDWARE<br/>config = PERF_COUNT_HW_CACHE_MISSES"];
    B -- "Software" --> G{"What kind?"};
    G -- "Context Switches" --> H["type = PERF_TYPE_SOFTWARE<br/>config = PERF_COUNT_SW_CONTEXT_SWITCHES"];
    G -- "Page Faults" --> I["type = PERF_TYPE_SOFTWARE<br/>config = PERF_COUNT_SW_PAGE_FAULTS"];

    J[Event Configured] --> K{"Counting or<br/>Sampling?"};
    D-->J; E-->J; F-->J; H-->J; I-->J;

    K -- "Counting" --> L["Read 64-bit value<br/>from file descriptor"];
    K -- "Sampling" --> M["Set sample_period or sample_freq<br/>Read samples from mmap'd buffer"];

    L --> N{"Scope?"};
    M --> N;

    N -- "This Thread" --> O["pid = 0<br/>cpu = -1"];
    N -- "Specific Process" --> P["pid = target_pid<br/>cpu = -1"];
    N -- "Specific CPU (all processes)" --> Q["pid = -1<br/>cpu = target_cpu"];

    O --> R[("Call perf_event_open")];
    P --> R;
    Q --> R;

One of the most critical fields is disabled. My recommendation: always initialize your event with disabled = 1. This creates the counter but doesn’t start it. You can then enable it precisely around the code you want to measure using an ioctl(fd, PERF_EVENT_IOC_ENABLE, 0) call, preventing noise from your program’s setup and initialization phases.

Start every counter in a disabled state and enable it via ioctl only for the critical section you intend to measure.

How do you use perf_event_open in code?

To use perf_event_open, you call it with the configured perf_event_attr struct, a process ID (or 0 for the current thread), a CPU index (or -1 for any CPU), and flags. A successful call returns a file descriptor. You then read an 8-byte (64-bit) integer from this file descriptor to get the current value of the performance counter.

Here’s a minimal C program that counts the number of instructions executed between two points in the code for the current thread.

#include <stdlib.h>
#include <stdio.h>
#include <unistd.h>
#include <string.h>
#include <sys/ioctl.h>
#include <linux/perf_event.h>
#include <asm/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(__NR_perf_event_open, hw_event, pid, cpu,
                   group_fd, flags);
    return ret;
}

int main(int argc, char **argv)
{
    struct perf_event_attr pe;
    long long count;
    int fd;

    memset(&pe, 0, sizeof(struct perf_event_attr));
    pe.type = PERF_TYPE_HARDWARE;
    pe.size = sizeof(struct perf_event_attr);
    pe.config = PERF_COUNT_HW_INSTRUCTIONS;
    pe.disabled = 1;
    pe.exclude_kernel = 1;
    pe.exclude_hv = 1;

    // pid=0 and cpu=-1 monitor the current thread on any CPU
    fd = perf_event_open(&pe, 0, -1, -1, 0);
    if (fd == -1) {
       fprintf(stderr, "Error opening leader %llx\n", pe.config);
       exit(EXIT_FAILURE);
    }

    ioctl(fd, PERF_EVENT_IOC_RESET, 0);
    ioctl(fd, PERF_EVENT_IOC_ENABLE, 0);

    // --- Critical section to be measured ---
    printf("Measuring instructions for this printf call...\n");
    // --- End of critical section ---

    ioctl(fd, PERF_EVENT_IOC_DISABLE, 0);
    read(fd, &count, sizeof(long long));

    printf("Used %lld instructions.\n", count);

    close(fd);
    return 0;
}

Compile and run it like this:

gcc -o measure_instr measure_instr.c
./measure_instr

The output will vary slightly, but it shows the concrete counter value.

Measuring instructions for this printf call...
Used 2345 instructions.

This direct, programmatic approach is powerful. It lets you embed performance assertions directly into your test suites or build adaptive systems that change behavior based on real-time hardware metrics. This is a level of control that higher-level tools, while useful, cannot provide. It is also the foundation for modern observability techniques described in The Fourth Signal: Introduction to OpenTelemetry Profiling.

Checklist for using `perf_event_open`

• Have I included <linux/perf_event.h>?
• Have I zeroed out my struct perf_event_attr with memset before setting fields?
• Is the size field of the struct set correctly (sizeof(struct perf_event_attr))?
• Did I create the counter with disabled = 1?
• Am I checking the return value of the perf_event_open call for -1?
• Am I using ioctl to RESET and ENABLE the counter just before my critical section?
• Am I using ioctl to DISABLE the counter immediately after?
• Am I read()ing a full 8 bytes (sizeof(long long)) into a 64-bit integer?
• Am I close()ing the file descriptor?

The file descriptor returned by perf_event_open is your handle to the counter; ioctl controls it and read queries it.

What are the alternatives to calling the syscall directly?

Calling perf_event_open directly is for experts who need fine-grained control with minimal dependencies. For most use cases, higher-level abstractions are more productive. The perf command is the standard for system-wide analysis, while libraries like libpfm4 and eBPF programs offer more structured programmatic access.

Here’s how they stack up:

Tool/API	Abstraction Level	Key Use Case	Winner For
perf_event_open syscall	Kernel API	Embedding hyper-specific counters into an application with zero extra dependencies.	Minimalist, high-performance C/C++/Rust applications.
libpfm4	C Library	Translating CPU-specific event names (e.g., MEM_LOAD_RETIRED.L3_MISS) to raw register values.	Writing portable profilers that work across CPU models.
perf CLI	Userspace Tool	System-wide profiling, flame graphs, and interactive debugging on a live system.	General-purpose performance analysis and troubleshooting.
eBPF programs	In-Kernel VM	Triggering actions in the kernel when a performance event occurs (e.g., record a stack trace on every 10,000th cache miss).	Dynamic, low-overhead observability without application restarts.

According to the official perf_event_open(2) man page, access to performance counters is governed by the /proc/sys/kernel/perf_event_paranoid sysctl setting. A value of 2 or higher (the default on many systems is 3 as of kernel 6.x) heavily restricts or disables access for non-root users, which is a key reason many developers stick to the perf tool run via sudo.

Default to using the perf command-line tool. Drop down to the raw syscall only when you need to programmatically embed a counter inside your application’s logic.

Bottom Line

The perf_event_open syscall is not a tool you’ll reach for daily. But when you hit the ceiling of what standard profilers can do, it’s the primitive that gives you ultimate control. Understanding this layer is key to diagnosing the most subtle performance issues and is essential knowledge for anyone building high-performance systems software on Linux.

FAQ

How do I find the config value for a specific hardware event like L1 cache misses?

You can use the perf tool itself. Run perf list cache to see symbolic names for cache events. For raw events specific to your CPU, you may need to consult vendor documentation (e.g., Intel or AMD software developer manuals) or use a library like libpfm4 to translate names to codes.

What’s the difference between sample_period and sample_freq?

You can only set one. sample_period configures the sampler to generate an event after a specific number of occurrences (e.g., every 1,000,000 cycles). sample_freq is a more convenient alternative where you specify a target rate (e.g., 1000 Hz), and the kernel automatically adjusts the period to achieve that average frequency.

Can perf_event_open cause significant performance overhead?

When used for simple counting, the overhead is extremely low—a few instructions to read the counter. When used for high-frequency sampling (e.g., thousands of samples per second), the overhead of handling interrupts and recording sample data (like stack traces) can become significant and impact application performance.

Do I need root privileges to use perf_event_open?

It depends on the perf_event_paranoid sysctl setting. A value of -1 allows anyone to use it. A value of >= 2 restricts access to kernel-level events, often requiring CAP_SYS_ADMIN capabilities (effectively, root). You can check the current value with cat /proc/sys/kernel/perf_event_paranoid.

How does this low-level data relate to modern observability?

This raw performance data is the ground truth. While higher-level systems like AI-Driven Observability: Proactive Insights for Cloud-Native focus on correlating signals across a distributed system, the data often originates from primitives like perf_event_open. Understanding the source helps you validate and interpret the insights from those more complex platforms.

Further Reading

• https://man7.org/linux/man-pages/man2/perf_event_open.2.html
• https://www.brendangregg.com/perf.html
• https://lwn.net/Articles/633458/

---

🚀 Ready to get hands-on? Spin up an interactive AI or Kubernetes Sandbox at Aicademy Labs for free.