LIBPERF-SAMPLING(7)

🦋 libperf-sampling — the sampling interface, explained by your fave ✨

okay so this is a page from the libperf Manual (yes, libperf-sampling(7), she's a section 7 girlie) and bestie, we're gonna get into it 💅

---

🌸 NAME 🌸

libperf-sampling — the sampling interface. that's it, that's the name, iconic

---

✨ DESCRIPTION ✨

so the sampling interface gives you an API to measure and get count for specific perf events. like, that's the whole vibe. 🫶

the following test tries to explain count on the sampling.c example.

ngl, it is by no means a complete guide to sampling — it just shows the libperf basic API for sampling. so like, don't come for her, she's doing her best 💖

sampling.c comes with the libperf package and can be compiled and run like this:

$ gcc -o sampling sampling.c -lperf
$ sudo ./sampling
cpu   0, pid      0, tid      0, ip     ffffffffad06c4e6, period                    1
cpu   0, pid   4465, tid   4469, ip     ffffffffad118748, period             18322959
cpu   0, pid      0, tid      0, ip     ffffffffad115722, period             33544846
cpu   0, pid   4465, tid   4470, ip         7f84fe0cdad6, period             23687474
cpu   0, pid      0, tid      0, ip     ffffffffad9e0349, period             34255790
cpu   0, pid   4465, tid   4469, ip     ffffffffad136581, period             38664069
cpu   0, pid      0, tid      0, ip     ffffffffad9e55e2, period             21922384
cpu   0, pid   4465, tid   4470, ip         7f84fe0ebebf, period             17655175
...

🚨 it requires root access, because it uses the hardware cycles event. no cap, you literally need sudo.

so sampling.c profiles/samples all CPUs with hardware cycles, and in a nutshell it does this whole routine:

• creates events
• adds them to the event list
• opens and enables events through the event list
• sleeps for 3 seconds
• disables events
• reads and displays recorded samples
• destroys the event list

---

🎀 first things first: init 🎀

the first thing you need to do before using libperf is to call the init function:

     12 static int libperf_print(enum libperf_print_level level,
     13                          const char *fmt, va_list ap)
     14 {
     15         return vfprintf(stderr, fmt, ap);
     16 }

     23 int main(int argc, char **argv)
     24 {
     ...
     40         libperf_init(libperf_print);

it will setup the library and sets function for debug output from library. 💫

the libperf_print callback will receive any message with its debug level, defined as:

enum libperf_print_level {
        LIBPERF_ERR,
        LIBPERF_WARN,
        LIBPERF_INFO,
        LIBPERF_DEBUG,
        LIBPERF_DEBUG2,
        LIBPERF_DEBUG3,
};

---

🦋 defining the cycles event 🦋

once the setup is complete we start by defining the cycles event using struct perf_event_attr:

     29         struct perf_event_attr attr = {
     30                 .type        = PERF_TYPE_HARDWARE,
     31                 .config      = PERF_COUNT_HW_CPU_CYCLES,
     32                 .disabled    = 1,
     33                 .freq        = 1,
     34                 .sample_freq = 10,
     35                 .sample_type = PERF_SAMPLE_IP|PERF_SAMPLE_TID|PERF_SAMPLE_CPU|PERF_SAMPLE_PERIOD,
     36         };

---

💜 preparing the CPUs map 💜

next step is to prepare the CPUs map.

in this case we will monitor all the available CPUs:

     42         cpus = perf_cpu_map__new_online_cpus();
     43         if (!cpus) {
     44                 fprintf(stderr, "failed to create cpus\n");
     45                 return -1;
     46         }

---

🌈 the event list 🌈

now we create libperf's event list, which will serve as holder for the cycles event:

     48         evlist = perf_evlist__new();
     49         if (!evlist) {
     50                 fprintf(stderr, "failed to create evlist\n");
     51                 goto out_cpus;
     52         }

we create libperf's event for the cycles attribute we defined earlier and add it to the list:

     54         evsel = perf_evsel__new(&attr);
     55         if (!evsel) {
     56                 fprintf(stderr, "failed to create cycles\n");
     57                 goto out_cpus;
     58         }
     59
     60         perf_evlist__add(evlist, evsel);

configure the event list with the cpus map and open the event:

     62         perf_evlist__set_maps(evlist, cpus, NULL);
     63
     64         err = perf_evlist__open(evlist);
     65         if (err) {
     66                 fprintf(stderr, "failed to open evlist\n");
     67                 goto out_evlist;
     68         }

---

🧚 memory maps AKA perf ring buffers 🧚

once the events list is open, we can create memory maps AKA perf ring buffers:

     70         err = perf_evlist__mmap(evlist, 4);
     71         if (err) {
     72                 fprintf(stderr, "failed to mmap evlist\n");
     73                 goto out_evlist;
     74         }

the event is created as disabled (note the disabled = 1 assignment up above ⬆️), so we need to enable the events list explicitly.

from this moment the cycles event is sampling. 🔥

we will sleep for 3 seconds while the ring buffers get data from all CPUs, then we disable the events list:

     76         perf_evlist__enable(evlist);
     77         sleep(3);
     78         perf_evlist__disable(evlist);

---

🍓 reading the samples 🍓

following code walks through the ring buffers and reads stored events/samples:

     80         perf_evlist__for_each_mmap(evlist, map, false) {
     81                 if (perf_mmap__read_init(map) < 0)
     82                         continue;
     83
     84                 while ((event = perf_mmap__read_event(map)) != NULL) {

                                    /* process event */

     108                         perf_mmap__consume(map);
     109                 }
     110                 perf_mmap__read_done(map);
     111         }

each sample needs to get parsed, so like, do the parsing bestie:

     85                         int cpu, pid, tid;
     86                         __u64 ip, period, *array;
     87                         union u64_swap u;
     88
     89                         array = event->sample.array;
     90
     91                         ip = *array;
     92                         array++;
     93
     94                         u.val64 = *array;
     95                         pid = u.val32[0];
     96                         tid = u.val32[1];
     97                         array++;
     98
     99                         u.val64 = *array;
     100                        cpu = u.val32[0];
     101                        array++;
     102
     103                        period = *array;
     104
     105                        fprintf(stdout, "cpu %3d, pid %6d, tid %6d, ip %20llx, period %20llu\n",
     106                                cpu, pid, tid, ip, period);

---

🎀 and finally, cleanup 🎀

we close the whole events list (both events) and remove it together with the threads map:

     113 out_evlist:
     114         perf_evlist__delete(evlist);
     115 out_cpus:
     116         perf_cpu_map__put(cpus);
     117         return err;
     118 }

cleanup arc complete, we love to see it ✨

---

😭 REPORTING BUGS 😭

report bugs to <linux-perf-users@vger.kernel.org[1]>. please be nice to the maintainers, they're people too 🫶

---

👑 LICENSE 👑

libperf is Free Software licensed under the GNU LGPL 2.1. periodt.

---

🌟 RESOURCES 🌟

https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git

go touch grass in the kernel tree, iykyk 🌱

---

💖 SEE ALSO 💖

• libperf(3)
• libperf-counting(7)

---

📝 NOTES 📝

1. linux-perf-users@vger.kernel.org — mailto:linux-perf-users@vger.kernel.org

---

so yeah, that's the whole page 💅 this was libperf-sampling(7) from the libperf manual, dated 11/01/2026 — go forth and sample, bestie, you're gonna slay 🔥🦋