cpu_sup(3)

📦

version 29.0.6 · 2 versions

29.0.6 · nixos 26.05, nixpkgs unstable, ubuntu stonking (latest)
28.5.0.8 · alpine 3.24

, in nixos 26.05, nixpkgs unstable, ubuntu stonking

✨ cpu_sup 💅✨

okay bestie, this is cpu_sup(3) from the Erlang Module Definition section, and it's brought to you by the os_mon girlies. let's get into it 🫶

🌸 NAME 🌸

cpu_sup — a CPU Load and CPU Utilization Supervisor Process 👑

💖 DESCRIPTION 💖

so cpu_sup is literally a process that supervises the CPU load and CPU utilization. it's part of the OS_Mon application — go peek at os_mon(6) if you want the lore. it's available for Unix, but the CPU utilization values (util/0,1) are only available on Solaris, Linux, FreeBSD and OpenBSD. not everywhere, okay? know the vibe of your platform 💅

The load values are proportional to how long a runnable Unix process has to sit in the run queue before it gets scheduled. so basically: higher value = more system load. The returned value divided by 256 gives you the figure that rup and top display. what shows up as 2.00 in rup is the load up to the second mark in xload. slay.

for example, rup displays a load of 128 as 0.50, and 512 as 2.00. math is mathing ✨

Now, if you wanna view load values as a percentage of machine capacity, this whole measuring thing presents a problem, because the load values are not restricted to a fixed interval 😭. In that case, this simple little transformation can turn your load value into a percentage:

PercentLoad = 100 * (1 - D/(D + Load))

D decides which load value gets associated with which percentage. pick D = 50 and that means 128 is 60% load, 256 is 80%, 512 is 90%, and so on. obsessed.

Another way to measure system load is to divide the number of busy CPU cycles by the total number of CPU cycles. that one gives you values in the 0-100 range immediately. however — and this is the tea 🍵 — this method hides the fact that a machine can be more or less saturated. so CPU utilization is honestly a better name than "system load" for this measure, no cap.

A server that receives just enough requests to never become idle will score a CPU utilization of 100%. if it receives 50% more requests, it will still score 100% 💀. but when you calculate system load with that percentage formula from earlier, the load increases from 80% to 87%. see the difference? that's the whole point.

The avg1/0, avg5/0, and avg15/0 functions are your girls for retrieving system load values, and util/0 and util/1 are the ones for CPU utilization values. iykyk 🧚

⚠️ heads up: when running on Linux, cpu_sup assumes the /proc file system is present and accessible by cpu_sup. if it's not, cpu_sup will terminate. so like... make sure /proc exists, bestie 🙈

👀 See Also

os_mon(3)

🦋 DATA TYPES 🦋

util_cpus() :: all | integer() | [integer()].

util_desc() :: {util_cpus(), util_value(), util_value(), []}.

util_state() :: user | nice_user | kernel | wait | idle.

util_value() :: [{util_state(), number()}] | number().

✨ FUNCTIONS ✨

`avg1() -> SystemLoad :: integer() | {error, any()}.`

Returns the average system load in the last minute, as described above. 0 represents no load, 256 represents the load reported as 1.00 by rup.