PCP-PIDSTAT(1)

🌸 PCP-PIDSTAT(1) — General Commands Manual 🌸

okay bestie, sit down, hydrate, and let me tell you about pcp-pidstat — it's the PCP girlies' take on task-watching, and she EATS 💅

---

✨ NAME ✨

pcp-pidstat — Report statistics for Linux tasks.

---

🎀 SYNOPSIS 🎀

pcp [pcp options] pidstat [-I] [-l] [-R] [-r] [-k] [-U [username]] [-V]
[-G processname] [-p pid1,pid2..]  [-t interval] [-s count] [-a archive]
[-B state] [-f format] [-Z timezone] [-z] [-?]

---

🦋 DESCRIPTION 🦋

So pcp-pidstat is literally for monitoring individual tasks running on your system, one by one, like a little spotlight on each process. 🫶

With all its different options it lets you peek at genuinely useful stuff about your processes — CPU percentage, memory and stack usage, scheduling and priority. All the good gossip. 😌

By default pcp-pidstat reports live data for the local host. That's the vibe out of the box.

---

👑 OPTIONS 👑

When you invoke it through the pcp(1) command, a whole squad of options becomes indirectly available to you: -h/--host, -a/--archive, -O/--origin, -s/--samples, -t/--interval, -Z/--timezone, plus several other pcp options. Go read PCPIntro(1) for the full description of those, bestie, I'm not typing all that out here. 💀

The extra command line options that are actually pcp-pidstat's own are:

• -I — In an SMP environment, this says the tasks' CPU usage should be divided by the total number of processors. Sharing is caring ✨
• -l — Display the process command name and all its arguments. Full name, no nickname energy.
• -R — Report real-time priority and scheduling policy info. The following values may be displayed:
  • UID — The real user identification number of the task being monitored.
  • USER — The name of the real user owning the task being monitored.
  • PID — The identification number of the task being monitored.
  • prio — The real-time 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. The following values may be displayed:
  • UID — The real user identification number of the task being monitored.
  • USER — The name of the real user owning the task being monitored.
  • PID — The identification number of the task being monitored.
  • minflt/s — Total number of minor faults the task has made per second, those which have not required loading a memory page from disk.
  • majflt/s — Total number of major faults the task has made per second, those which have required loading a memory page from disk.
  • VSZ — Virtual Size: The virtual memory usage of entire task in kilobytes.
  • RSS — Resident Set Size: The non-swapped physical memory used by the task in kilobytes.
  • %MEM — The tasks currently used share of available physical memory.
  • Command — The command name of the task.
• -k — Report stack utilization. The following values may be displayed:
  • UID — The real user identification number of the task being monitored.
  • USER — The name of the real user owning the task being monitored.
  • PID — The identification number of the task being monitored.
  • StkSize — The amount of memory in kilobytes reserved for the task as stack, but not necessarily used.
  • StkRef — The amount of memory in kilobytes used as stack, referenced by the task.
  • Command — The command name of the task.
• -U [username], --user-name[=username] — Display the real user name of the tasks being monitored instead of the UID. And if you pass username, then only tasks belonging to that specified user get displayed. Filtered. Curated. 🎀
• -V, --version — Print the version number then exit. Short and sweet, periodt.
• -G processname, --process-name=processname — Display only processes whose command name includes the string processname. Heads up: this string can be a regular expression. 👀
• -p pid1,pid2.., --pid-list=pid1,pid2.. — Display only processes with the listed PIDs.
• -t interval, --interval=interval — Set the interval between two samples. The default is one second.
• -s count, --samples=count — Set the number of samples to be displayed. Important lore: since the first sample is used for the rate conversion of some of the metrics, the total number of samples reported is one less than count. The default is continuous.
• -a archive, --archive=archive — Causes pcp-pidstat to use the specified archive rather than connecting to PMCD. The argument to -a is a comma-separated list of names, each of which may be the base name of an archive or the name of a directory containing one or more archives.
• -B — Report process states. The argument to -B is one of the following:
  • detail — Show total time processes have spent in each of the 5 different states
  • all — Show total time processes spent in their current state
  • [R,S,T,D,Z] — A comma separated list of process states. For example, -B R,S will report processes currently in either R or S states and not report processes currently in any other states.
• -f — Use the format string for formatting the timestamp. The format will be used with the python(1) datetime.strftime method, which is similar to that described in strftime(3). An empty format string (i.e, "") will remove the timestamps from the output. The default with stdout is %H:%M:%S.
• -Z timezone, --timezone=timezone — By default, pcp-pidstat reports the time of day according to the local timezone on the system where pcp-pidstat is run. The -Z option changes the timezone to timezone in the format of the environment variable TZ as described in environ(7).
• -z , --hostzone — Change the reporting timezone to the local timezone at the host that is the source of the performance metrics. When you're replaying a PCP archive that was captured in a foreign timezone, you would almost always use -z (the default reporting timezone is the local timezone, which may not be the same as the timezone of the PCP archive). Timezone glow-up. 🌈
• -? , --help — Display usage message and exit.

---

📝 NOTES 📝

pcp-pidstat is inspired by the pidstat(1) command and aims to be command line and output compatible with it. Respecting her ancestors fr fr. 🙏

---

💜 PCP ENVIRONMENT 💜

Environment variables with the prefix PCP_ are used to parameterize the file and directory names used by PCP. On each installation, the file /etc/pcp.conf contains the local values for these variables. The $PCP_CONF variable may be used to specify an alternative configuration file, as described in pcp.conf(5).

For environment variables affecting PCP tools, see pmGetOptions(3).

---

🔥 SEE ALSO 🔥

PCPIntro(1), pcp(1), pidstat(1), python(1), pmParseInterval(3), strftime(3) and environ(7).

---

okay that's the whole page bestie, you're officially educated 💖 this one came from Performance Co-Pilot (PCP) — same PCP-PIDSTAT(1) energy, General Commands Manual vibes — and you can find her in the PCP section. go forth and monitor ur tasks, you main character. 👑✨