PCP-SS(1)

💖 pcp-ss 💖

okay bestie, welcome to the pcp-ss manual page — this is the General Commands Manual entry for pcp-ss, and it's literally the cutest way to report socket statistics. buckle up 🎀

---

✨ NAME ✨

pcp-ss — report socket statistics 🦋

---

✨ SYNOPSIS ✨

pcp [pcp options] ss [ss options]

---

✨ DESCRIPTION ✨

so pcp-ss reports socket statistics, and those stats are collected by the pmdasockets(1) PMDA agent. the whole vibe is that this command is intended to be reasonably compatible with a lot of the ss(8) command line options and reporting formats — but it ALSO serves up the advantages of local or remote monitoring (in live mode) plus historical replay from a previously recorded PCP archive. main character energy, honestly. 👑

ngl though, there's a whole thing you need to know: since ss(1) has SO many command line options, and a lot of them are the same as standard PCP command line options as described in PCPIntro(1), the pcp-ss tool should always be invoked by users using the pcp front-end. that way, standard PCP commandline options like -h, -a, -S, -T, -O, -z, etc can be passed without conflict with ss(1) options. no drama, no collisions. 💅 see the EXAMPLES sections below for typical usage and command lines.

Live mode uses the pcp -h host option and requires the pmdasockets(1) PMDA to be installed and enabled on the target host (local or remote) — peep pmdasockets(1) for details on how to enable the sockets PMDA on a particular host. the default source is live metrics collected on localhost, if neither of the -h or -a options are given. 🏠

Historical/archive replay uses the pcp -a archive option, where archive is the basename of a previously recorded PCP archive. the archive replay feature is particularly useful because socket statistics can be reported for a designated time using the pcp --origin option (which defaults to the start time of the archive). time travel but make it sockets ⏰✨

---

🌈 EXAMPLES 🌈

• pcp ss — display default basic socket information for the local host. this includes Netid (tcp, udp, etc), State (ESTAB, TIME_WAIT, etc), Recv-Q and Send-Q queue lengths and the local and peer address and port for each socket. the whole starter pack fr fr 💖
• pcp -h somehost ss -noemitauO — display the same basic socket information as above for the host somehost, which may be the default localhost. the additional command line arguments (-noemitauO) display one line per socket (-O), numeric (-n) service names (default), timer information (-o), extended socket details (-e), socket memory usage (-m), internal TCP information (-i), both udp (-u) and tcp sockets (-t) and both listening and non-listening sockets (-a). okay that's a LOT of letters but every single one is pulling its weight 🫶
• pcp -a somearchive -S'@Wed 16 Jun 2021 12:57:21' ss -noemitauO — display the same information as the above example, but for the archive somearchive starting at the given time Wed 16 Jun 2021 12:57:21. note the literal @ prefix is required for an absolute time, see PCPIntro(1) for details. the archive must of course contain data for the requested time. you can use pmlogdump -l somearchive to examine the time bounds of somearchive. ⭐
• pcp -a somearchive -O-0 ss -noemitauO — as above, but with an offset of zero seconds (-O-0) before the current end of somearchive, i.e. the most recently logged data. note that somearchive may be currently growing (i.e. being logged with pmlogger(1)). it's giving live-ish 🌱

---

✨ OPTIONS ✨

due to the large number of options supported by pcp-ss, the pcp(1) command should always be used to invoke pcp-ss in order to specify options such as the metrics source (host or archive) and also (in archive mode), the requested start time or offset, and timezone using the following options:

• -h, --host — the remote hostname to connect to in live mode. 🌐
• -a, --archive — the archive file to use for historical sampling 📼
• -O, --origin — the time offset to use within an archive (implies -a) ⏳
• -S, --start — the start time (e.g. in ctime(3) format) to use when replaying an archive ⏰
• -Z, --timezone — use a specific timezone. since pcp-ss doesn't report timestamps, this only affects the interpretation of an absolute starting time (-S) or offset (-O). 🌍
• -z, --hostzone — in archive mode, use the timezone of the archive rather than the timezone on the local machine running pcp-ss. the timezone, start and finish times of the archive may be examined using pmlogdump(1) with the -L option. 🕰️

the above pcp options become indirectly available to the pcp-ss command via environment variables — refer to PCPIntro(1) for a complete description of these options. iykyk ✨

and now, the additional command line options available for pcp-ss itself:

• -h, --help — show help message and exit 🙋
• -V, --version — output version information 🏷️
• -n, --numeric — don't resolve service names (currently always set) 🔢
• -a, --all — display all sockets 👀
• -l, --listening — display listening sockets 👂
• -o, --options — show timer information ⏱️
• -e, --extended — show detailed socket information 📋
• -m, --memory — show socket memory usage 🧠
• -i, --info — show internal TCP information 🔍
• -4, --ipv4 — display only IP version 4 sockets 4️⃣
• -6, --ipv6 — display only IP version 6 sockets 6️⃣
• -t, --tcp — display only TCP sockets 🧵
• -u, --udp — display only UDP sockets 📮
• -H, --noheader — suppress header line 🙈
• -O, --oneline — socket's data printed on a single line ➡️

lowkey important: -h shows up twice in this page — once as the PCP --host option and once as pcp-ss's own --help. that's exactly why you always go through the pcp front-end, bestie. no cap. 💅

---

🌸 REPORT 🌸

the columns in the pcp-ss report vary according to the command line options and have the same interpretation as described in ss(8).

one difference with pcp-ss is that the first line in the report begins with # Timestamp followed by the timestamp (in the requested timezone, see -z and -Z above) of the sample data from the host or archive source. following the timestamp is the currently active filter string for the metrics source. in archive mode, the active filter can be changed dynamically, even whilst the archive is being recorded. 🤯

this is different to ss(8) where the filter is optionally specified on the command line of the tool and is always 'live', i.e. ss(8) does not support retrospective replay. with pcp-ss, the filter is stored in the back-end PMDA, see pmdasockets(1), in the metric network.persocket.filter. the default filter is state connected, which can be changed by storing a new string value in the network.persocket.filter metric using pmstore(1), e.g.

pmstore network.persocket.filter "state established"

this will override the persistent default filter, which is stored in a PMDA configuration file and loaded each time the sockets PMDA is started. see pmdasockets(1) for further details and see ss(8) for details of the filter syntax and examples. 🎀

---

🧚 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), pmdasockets(1), pmlogger(1), pcp.conf(5) and ss(8).

---

that's the whole page, bestie — you ate it. 👑💅

and a lil sign-off for the record: this came from Performance Co-Pilot, the PCP collection, and the manual page is PCP-SS(1). 🫶✨