PIDSTAT(1)

💖 pidstat(1) 💖

Linux User's Manual ✨ pidstat is the manual name, bestie 🦋

🌸 NAME 🌸

pidstat - Report statistics for Linux tasks. 📊

🎀 SYNOPSIS 🎀

pidstat [ -d ] [ -H ] [ -h ] [ -I ] [ -l ] [ -R ] [ -r ] [ -s ] [ -t ] [ -U [ username ] ] [ -u ] [ -V ] [ -v ] [ -w ] [ -C comm ] [ -G process_name ] [ --dec={ 0 | 1 | 2 } ] [ --human ] [ -o JSON ] [ -p { pid[,...] | SELF | ALL } ] [ -T { TASK | CHILD | ALL } ] [ interval [ count ] ] [ -e program args ]

🌷 DESCRIPTION 🌷

okay so pidstat is the command you use to keep an eye on the individual tasks the Linux kernel is currently juggling 👀. It spits its stats out to standard output for every task you pick with -p, or for literally every task on the system if you use -p ALL 💅. If you don't select any tasks at all, that's the same as -p ALL, but only the active tasks (the ones with non-zero stats) show up in the report. no cap, very helpful 🫶

It can also keep tabs on the child processes of whatever tasks you've selected. Check out -T below for the tea on that one ☕.

The interval parameter is how many seconds go by between each report ⏰. If you give it a value of 0 (or you don't give any parameters at all), the stats are reported for the time since the system booted 🥹. The count parameter only works alongside interval, and only if interval isn't zero. It decides how many reports get generated, spaced interval seconds apart ✨. If you give interval but skip count, pidstat just keeps reporting nonstop, iykyk 🙈.

You can pick out specific task activities with flags 🚩. And if you don't use any flags? You only get CPU activity, periodt 💜.

💅 OPTIONS 💅

• -C comm — Only show tasks whose command name includes the string comm. Yes, this string can be a regular expression, we love a power move 🔥.
• -d — Report I/O statistics. This only works on kernels 2.6.20 and later, so no old-school vibes 🕰️. Here's what you'll see:
  • UID — The real user ID number of the task being monitored 🆔.
  • USER — The name of the real user who owns the task being monitored 🧑.
  • PID — The ID number of the task being monitored 🔢.
  • kB_rd/s — How many kibibytes the task has made get read from disk per second 📖.
  • kB_wr/s — How many kibibytes the task has caused, or is about to cause, to get written to disk per second ✍️.
  • kB_ccwr/s — How many kibibytes that were headed for disk got cancelled by the task. This can happen when the task truncates some dirty pagecache. In that case, some I/O that another task got credited for won't actually happen 💀.
  • iodelay — The block I/O delay of the task being monitored, measured in clock ticks ⏱️. This includes the delays spent waiting for sync block I/O to finish, and for swapin block I/O to finish too 🐢.
  • Command — The command name of the task 🎬.
• --dec={ 0 | 1 | 2 } — Pick how many decimal places you want, anywhere from 0 to 2. The default is 2 💯.
• -e program args — Run program with the given args and monitor it with pidstat. pidstat stops once program finishes 🏁. You have to give the interval parameter a non-zero value for this one 🫡.
• -G process_name — Only show processes whose command name includes the string process_name. Regular expressions are welcome here too 😌. If you use -t together with -G, the threads that belong to that process get shown as well, even if their command name doesn't include process_name 🧵.
• -H — Show the timestamp in seconds since the epoch 🕰️.
• -h — Show all activities horizontally on one single line, and skip the average statistics at the end of the report 📏. This is made so other programs can parse it more easily 🤖.
• --human — Print sizes in a human readable format, like 1.0k or 1.2M 🧁. The units shown with this option replace any other default units attached to the metrics, like kibibytes or sectors 🪄.
• -I — On an SMP system, this tells pidstat to divide the tasks' CPU usage (the stuff -u shows) by the total number of processors 🧮.
• -l — Show the process command name and all of its arguments 📜.
• -o JSON — Show the stats in JSON (JavaScript Object Notation) format 🧾. The field order in JSON output is undefined, and new fields might get added in the future, so don't lock your code to one exact order 🙃.
• -p { pid[,...] | SELF | ALL } — Pick the tasks (processes) you want stats for 🎯. pid is the process ID number. The SELF keyword means "report on the pidstat process itself" 🪞, while the ALL keyword means "report on every single task the system manages" 🌍.
• -R — Report realtime priority and scheduling policy info 🚦. Here's the lineup:
  • UID — The real user ID number of the task being monitored 🆔.
  • USER — The name of the real user who owns the task being monitored 🧑.
  • PID — The ID number of the task being monitored 🔢.
  • prio — The realtime priority of the task being monitored 🥇.
  • policy — The scheduling policy of the task being monitored 📋.
  • Command — The command name of the task 🎬.
• -r — Report page faults and memory utilization 🧠.

When you're looking at individual tasks, you can see:

• UID — The real user ID number of the task being monitored 🆔.
• USER — The name of the real user who owns the task being monitored 🧑.
• PID — The ID number of the task being monitored 🔢.
• minflt/s — The total number of minor faults the task made per second. These are the ones that didn't need a memory page loaded from disk 🙌.
• majflt/s — The total number of major faults the task made per second. These are the ones that did need a memory page loaded from disk 😬.
• VSZ — Virtual Size: the virtual memory usage of the entire task, in kibibytes 🌌.
• RSS — Resident Set Size: the non-swapped physical memory the task is using, in kibibytes 💾.
• %MEM — The task's currently used share of the available physical memory 🥧.
• Command — The command name of the task 🎬.

When you're looking at global stats for tasks and all their children, you can see:

• UID — The real user ID number of the task being monitored, along with its children 🆔.
• USER — The name of the real user who owns the task being monitored, along with its children 🧑.
• PID — The ID number of the task being monitored, along with its children 🔢.
• minflt-nr — The total number of minor faults made by the task and all of its children, collected during the interval 🫧.
• majflt-nr — The total number of major faults made by the task and all of its children, collected during the interval 🫠.
• Command — The command name of the task being monitored, along with its children 🎬.

• -s — Report stack utilization 🥞. The values you can see are:
  • UID — The real user ID number of the task being monitored 🆔.
  • USER — The name of the real user who owns the task being monitored 🧑.
  • PID — The ID number of the task being monitored 🔢.
  • StkSize — The amount of memory in kibibytes reserved for the task as stack, but not necessarily used 📦.
  • StkRef — The amount of memory in kibibytes actually used as stack and referenced by the task 👀.
  • Command — The command name of the task 🎬.
• -T { TASK | CHILD | ALL } — This decides what pidstat monitors 🔍. The TASK keyword reports stats for individual tasks, and that's the default 🏠. The CHILD keyword reports stats globally for the selected tasks and all their children 👨‍👩‍👧. The ALL keyword does both: individual tasks and the global stats for the selected tasks and their children 🌈.

Note: Global stats for tasks and all their children aren't available for every pidstat option 🙅‍♀️. Also, these stats aren't necessarily relevant to the current time interval. A child process's stats only get collected when it finishes or gets killed ⚰️.

• -t — Also show stats for the threads linked to the selected tasks 🧵.

This option adds these values to the reports:

• TGID — The ID number of the thread group leader 👑.
• TID — The ID number of the thread being monitored 🪡.

• -U [ username ] — Show the real user name of the tasks being monitored instead of the UID 🧑‍🤝‍🧑. If you give username, only the tasks that belong to that user will show up 💁.
• -u — Report CPU utilization 🔥.

When you're looking at individual tasks, you'll see:

• UID — The real user ID number of the task being monitored 🆔.
• USER — The name of the real user who owns the task being monitored 🧑.
• PID — The ID number of the task being monitored 🔢.
• %usr — The percentage of CPU the task used while running at the user level (application), with or without nice priority 🎧. Heads up: this does NOT include time spent running a virtual processor 🙅.
• %system — The percentage of CPU the task used while running at the system level (kernel) 🛠️.
• %guest — The percentage of CPU the task spent in a virtual machine, running a virtual processor 🖥️.
• %wait — The percentage of CPU the task spent waiting to run ⏳.
• %CPU — The total percentage of CPU time the task used 💯. On an SMP system, the task's CPU usage gets divided by the total number of CPUs if you've put -I on the command line 🧮.

• CPU — the processor number the task is hanging out on 🧠
• Command — the command name of the task ✨

When you're looking at global stats for a task and all of its children, you might see these 💜

• UID — the real user ID of the task being watched, along with its children 🎀
• USER — the name of the real user who owns that task and its children 🫶
• PID — the ID number of the task being watched, children included 🔢
• usr-ms — the total milliseconds the task and its children spent running at the user level (apps 💅), with or without nice priority, during the interval. Heads up: this does NOT count time spent running a virtual processor 🙅‍♀️
• system-ms — the total milliseconds the task and its children spent at the system level (kernel 🧚), during the interval
• guest-ms — the total milliseconds the task and its children spent inside a virtual machine, running a virtual processor 🌈
• Command — the command name of the task, plus its children 🍓

---

• -V — prints the version number, then exits. Simple, iconic, done 👑
• -v — reports values from some kernel tables 🦋 You'll see these fields:
  • UID — the real user ID of the task being monitored
  • USER — the name of the real user who owns the task being monitored
  • PID — the ID number of the task being monitored
  • threads — how many threads belong to the current task 🧵
  • fd-nr — how many file descriptors belong to the current task 📂
  • Command — the command name of the task
• -w — reports task switching activity 🔄 Heads up: this one only works on kernels 2.6.23 and later ⚠️ You'll see:
  • UID — the real user ID of the task being monitored
  • USER — the name of the real user who owns the task being monitored
  • PID — the ID number of the task being monitored
  • cswch/s — how many voluntary context switches the task made per second. That's when a task blocks itself because it needs a resource that isn't available right now 😴
  • nvcswch/s — how many non-voluntary context switches the task made per second. That's the drama one: a task runs for its whole time slice and then gets forced to give up the processor 😤
  • Command — the command name of the task

✨ ENVIRONMENT ✨

okay so pidstat pays attention to these environment variables, so you can customise your vibe 💖

• S_COLORS — by default, stats show up in color when the output is going to a terminal 🌈 Use this one to change things. The possible values are never, always or auto (and auto is the same as the default, so you're already set 🫶). Also, don't read into the colors! Red or yellow doesn't mean something is wrong, it just marks different ranges of values 💅
• S_COLORS_SGR — this one sets the colors and other text attributes used to display stats in the terminal 🎨 Its value is a colon-separated list of capabilities, and the default is I=32;22:N=34;1:W=35;1:X=31;1:Z=34;22. The capabilities you can use are:
  • I= — the SGR (Select Graphic Rendition) substring for item values, like PID, UID or CPU number 🔢
  • N= — the SGR substring for non-zero statistics values and for task names 💜
  • W= (or M=) — the SGR substring for percentage values in the range from 75% to 90% (or in the range 10% to 25%, depending on what the metric means) ⚠️
  • X= (or H=) — the SGR substring for percentage values greater than or equal to 90% (or lower than or equal to 10%, depending on the metric) 🚨
  • Z= — the SGR substring for zero values and for thread names 🤍
• S_TIME_FORMAT — if this variable exists and its value is ISO, the current locale gets ignored when the date is printed in the report header 🗓️ pidstat will use the ISO 8601 format (YYYY-MM-DD) instead, and the timestamp will be ISO 8601 compliant too ✨

✨ EXAMPLES ✨

okay now for the fun part, bestie 🎀 here are some combos you can copy:

pidstat 2 5

Shows five reports of CPU stats for every active task on the system, at two second intervals 💅

pidstat -r -p 1643 2 5

Shows five reports of page faults and memory stats for PID 1643, at two second intervals 🧠

pidstat -C "fox|bird" -r -p ALL

Shows global page faults and memory stats for every process whose command name includes the string "fox" or "bird" 🦊🐦

pidstat -T CHILD -r 2 5

Shows five reports of page faults stats at two second intervals for the child processes of all tasks on the system 👶 Only child processes with non-zero stats get displayed, so no clutter 🫶

✨ BUGS ✨

⚠️ the /proc filesystem must be mounted for pidstat to work at all. No /proc, no vibes 💀

Even though pidstat shows units that look like kilobytes (kB), megabytes (MB)..., it's actually using kibibytes (kiB), mebibytes (MiB)... 🤓 A kibibyte is 1024 bytes, and a mebibyte is 1024 kibibytes. Lowkey a plot twist 🙈

✨ FILES ✨

/proc is where the various files with system statistics live 📁🧚

✨ AUTHOR ✨

Sebastien Godard (sysstat <at> orange.fr) 👑 the legend behind it 🫶

✨ SEE ALSO ✨

sar(1), top(1), ps(1), mpstat(1), iostat(1), vmstat(8) — go check these out, they're giving 🦋

For more, peep https://github.com/sysstat/sysstat and https://sysstat.github.io/ 🌸

---

bestie, that's the whole thing 💖 pidstat, sysstat-approved, from the Linux crew, last updated JANUARY 2025, and you are officially a PIDSTAT(1) expert now 🎀✨👑