PERFEVENT.CONF(5)

💖 PERFEVENT.CONF(5) 💖

okay so bestie, welcome to the perfevent.conf manual page — section 5 of the File Formats Manual, and yes, the whole thing is literally about one config file, and it ate. let's go 🫶

---

✨ NAME ✨

perfevent.conf — the Performance Co-Pilot perfevent PMDA configuration file 🎀

---

✨ SYNOPSIS ✨

$PCP_PMDAS_DIR/perfevent/perfevent.conf

---

✨ DESCRIPTION ✨

So like, this file perfevent.conf is the whole vibe check for which hardware performance counters the perfevent PMDA turns on. That's it, that's the job. 💅

The config file is basically a list of events that should be enabled for each PMU. The perfevent PMDA figures out which PMUs are actually present, then programs the events you configured. And if multiple PMUs are available? The PMDA uses the order of the entries in the config file to decide which PMU settings to use. Entries at the top of the file have higher precedence, no cap. Only one PMU configuration setting is used — one and done, periodt.

The config file may also contain perf derived events. A derived event has a list of events which must be listed as base events. The values for the counters in the derived events are aggregated and displayed. 🦋

---

✨ FILE FORMAT ✨

The file is made of one or more groups of PMUs, plus the events that go with them. iconic structure honestly.

The PMU identification string goes in brackets, and one or more events are listed below it, one per line.

["PMU identification string"]
EVENT_NAME [CPU OPTION]
...

For derived events, you can specify one or more groups of events, where counters in one group can be specific to one architecture and the counters in another group can be specific to some other architecture. Or, only one group can be specified. EVENT_NAME_1, EVENT_NAME_2 etc. belong to group 1 and EVENT_NAME_3, EVENT_NAME_4 belong to group 2 and so on. If any of the events in the first group is not available, the entire group will be discarded. And then the next group gets checked. The first group with all the events available will be activated and monitored — main character group energy 👑

The derived perf event is enclosed in brackets along with :derived as a suffix. Note that the EVENT_NAME listed under a derived event must be present as a base event in the configuration file. And all the events under a particular derived perf event group must have the same CPU_OPTION. || acts as a separator for different groups inside a single derived event. The syntax is:

[event:derived]
EVENT_NAME_1 [CPU_OPTION] [scale]
EVENT_NAME_2 [CPU_OPTION] [scale]
...
||
EVENT_NAME_3 [CPU_OPTION] [scale]
EVENT_NAME_4 [CPU_OPTION] [scale]
...

🌸 the available event cpu options are as follows 🌸

• cpu — to add the counter to all cpus in the system
• cpu_rr — to add to one of the cpus in a round-robin allocation strategy
• node — to add the counter to the first cpu in each numa node
• node_rr — to add the counter to the cpus in each numa node in a round-robin allocation strategy
• [N] — where N is the numerical digit of the CPU index

if the CPU option is absent then the event is programmed on all cpus. (default behaviour, she's flexible 💜)

scale is applicable for the counters in derived events. If scale is given, the counters will be scaled to their respective values. The options are as follows:

• a float value — Can be a simple float value, or a value in scientific notation.
• perf_scale — The scale will be taken from the kernel sysfs scale file entry for that event. Its generally specified in /sys/bus/event_source/device/events/<event_name>.scale

If no scale is given, the default scale will be taken as 1.0. 💫

Blank lines are ignored. Lines that begin with the # sign are ignored. (so go ahead and comment your heart out bestie 🙈)

Multiple, comma separated, PMUs may be specified in the PMU definition.

---

✨ SEE ALSO ✨

pmdaperfevent(1).

---

and that's the whole page, you're welcome 💖 this one's from Performance Co-Pilot, courtesy of PCP, and it's the PERFEVENT.CONF(5) page — go forth and configure your counters, you absolute legend 🎀✨🌈