CPUSTAT(8)

💅 CPUSTAT — a lil' tool that measures CPU utilization ✨

okay so bestie, welcome to the cpustat manual, from the System Manager's Manual section 8 🫶. Yes section 8, that's the sysadmin/voodoo section, we're in our grown-and-sexy era. Let's get into it 💖

---

🌸 NAME 🌸

cpustat — a tool to measure CPU utilization.

---

✨ SYNOPSIS ✨

cpustat [ options ] [delay [count]]

---

🦋 DESCRIPTION 🦋

So like, cpustat is this program that dumps the CPU utilization of the tasks that are currently running (and by "tasks" we mean processes or kernel threads, both of them count, no gatekeeping here 💜). It's genuinely so useful for monitoring long-lived processes on your system — daemons, kernel threads, and your regular everyday user processes. iykyk.

Here's the tea though: cpustat only shows you the tasks that actually measured some change in their CPU activity between each sample interval. And how does it know? Because of an increment in the CPU tick count stats of utime and stime in /proc/$pid/stat. So basically it only reports activity from busy tasks that are still alive at the moment of each sample snapshot. Which means — and this is important, bestie — it will not account for very short lived processes that pop in and out between each sample period. They're the ghosts. We don't see them. 🙈

For each running task that consumed some CPU during the sample time, here's everything that gets displayed, no cap:

• %CPU — Total CPU used (in percent)
• %USR — CPU used in user space (in percent)
• %SYS — CPU used in system (kernel) space (in percent)
• PID — Process ID
• S — Process State
• CPU — CPU used by the process at time of sampling.
• Time — Total CPU time used by the process since it started.
• Task — Process command line information (from process cmdline or comm fields)

And the reason it's built this way? cpustat was designed to try and minimize the CPU overhead of process statistics gathering and reporting. It is therefore ideal for small embedded devices where CPU is limited and where measuring CPU utilisation may affect the overall CPU statistics. Lowkey self-aware of it. For this reason, it is not as complex as tools such as top(1) that have a more feature rich user interface. We are simple. We are efficient. We are iconic. 👑

---

🎀 PROCESS STATE CODES 🎀

• R — Running
• S — Sleeping
• D — Waiting, Disk Sleep
• T — Stopped
• t — Tracing stopped
• W — Paging
• X or x — Dead
• K — Wakekill
• W — Waking
• P — Parked

---

💅 OPTIONS 💅

the cpustat options are as follow, and yes we're listing every single one because you deserve the full menu, bestie 🍓:

• -a — calculate CPU utilisation based on all CPUs. For example, if a process is using 100% of 1 CPU and the system has 4 CPUs, then the utilisation will show as 25%. The default is to show utilisation on a per CPU basis.
• -c — get command information from process comm field.
• -d — strip directory basename off command information.
• -D — compute and show the distribution of CPU utilisation by task and by CPU.
  • By task, this breaks the CPU utilisation of each task into 20 ranges from minimum to the maximum and shows the count of tasks found at in that particular utilisation range. Useful to see any outliers and to characterize the typical per task usage of the CPU.
  • By CPU, this shows the user and system CPU utilisation by per CPU.
• -g — show grand total of CPU utilisation statistics at the end of the run. This is the total cumulatave CPU used by each process, averaged over the entire run duration.
• -h — show help.
• -i — ignore cpustat in the statistics.
• -l — show long (full) command information.
• -n task_count — only display the first task_count number of top tasks.
• -p PID — only display process that matches the given PID.
• -q — run quietly, only really makes sense with -r option.
• -r csv_file — output gathered data in a comma separated values file. This can be then imported and graphed using your favourite open source spread sheet. The %CPU utilisation (system and user) for each process at each sample time is output into a table.
• -s — show short command information.
• -S — show time stamp. If the -r option is used then an extra column appears in the CSV output file with the time of day for each sample.
• -t threshold — ignore samples where the CPU usage delta per second less than the given threshold.
• -T — calculate total CPU utilisation.
• -x — show extra CPU related statistics, namely: CPU load average over 1, 5 and 10 minutes, CPU frequency (average of all online CPU frequencies), number of CPUs online.
• -X — run in curses based "top" like mode; this will make cpustat consume more CPU cycles as it adds on more display handling overhead.

⚠️ heads up on -X: it's giving top energy but it will eat more CPU cycles because of all the extra display handling overhead. Cute but expensive. 💀

---

🌈 EXAMPLES 🌈

cpustat

cpustat

Dump CPU stats every second until stopped.

---

cpustat -n 20 60

cpustat -n 20 60

Dump the top 20 CPU consuming tasks every 60 seconds until stopped.

---

cpustat 10 5

cpustat 10 5

Dump CPU stats every 10 seconds just 5 times.

---

cpustat -x -D -a 1 300

cpustat -x -D -a 1 300

Gather stats every second for 5 minutes with extra CPU stats and show CPU utilisation distributions per task and per CPU at the end of the run. Also, scale CPU utilisation by the number of CPUs so that 100% utilisation means 100% of all CPUs rather than 100% of 1 CPU.

---

👀 SEE ALSO 👀

forkstat(8), eventstat(8), vmstat(8), top(1)

---

💖 AUTHOR 💖

cpustat was written by Colin Ian King <colin.i.king@gmail.com>

This manual page was written by Colin Ian King <colin.i.king@gmail.com>, for the Ubuntu project (but may be used by others).

---

🌟 COPYRIGHT 🌟

Copyright © 2011-2021 Canonical Ltd, Copyright © 2021-2025 Colin Ian King

This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

---

okay that's the whole page, you're officially a cpustat girlie now 💅✨ this was the CPUSTAT(8) page from the System Manager's Manual, and the version you're holding is dated January 8, 2024 — go forth and measure some CPU, bestie, ily, periodt 🎀🦋💜