PMDASOCKETS(1)

💖 PMDASOCKETS 💖

okay bestie, so pmdasockets — say it with me — is the sockets statistics PMDA, like a whole Performance Metrics Domain Agent whose entire job is serving up metric values for the sockets chillin' on your local system right now. it's giving "who's connected and what are they doing" energy ✨

---

✨ SYNOPSIS ✨

$PCP_PMDAS_DIR/sockets/pmdasockets [-D debug]

---

🌸 DESCRIPTION 🌸

pmdasockets is a Performance Metrics Domain Agent (PMDA) that exports metric values for the current sockets on the local system. that's it, that's the whole gig 💅

right now it collects its data through the ss(8) utility, and it requires that program to be installed or it simply cannot function. ngl, this dependency may change in the future, but for now? ss(8) or nothing, periodt.

---

🎀 INSTALLATION 🎀

to install (enable) the sockets PMDA, do the following as root:

# cd $PCP_PMDAS_DIR/sockets
# ./Install

to uninstall (disable), do the following as root:

# cd $PCP_PMDAS_DIR/sockets
# ./Remove

pmdasockets is launched by pmcd(1) and should never be executed directly — not me catching you trying to run it by hand 🙈. the Install and Remove scripts handle the whole "hey pmcd(1), this agent just got installed/removed" notification thing for you. iconic behaviour tbh.

---

🦋 FILTER CONFIGURATION 🦋

the string valued metric network.persocket.filter is the main character here — it specifies the ss(1) filter that gets applied to optionally select socket states, IP addresses and other options that pmdasockets will collect (to populate its instance domain) 💖

this filter is loaded on PMDA startup from the file $(PCP_SYSCONF_DIR)/sockets/filter.conf (typically /etc/pcp/sockets/filter.conf) and it defaults to state connected, meaning only sockets in the connected state will be included. lowkey exclusive, but okay.

• you can change it persistently by editing filter.conf as the root user 🌈
• you can also change it dynamically after the PMDA has started, using pmstore(1) to store a new filter string in the network.persocket.filter metric 🔥

e.g.

# pmstore network.persocket.filter "state all"

will change the filter to include sockets in all states. slay.

⚠️ heads up bestie: a dynamically stored filter is not persisted across PMDA restarts or reboots. if you want it to stick, edit the config file for a persistent change. fr fr.

for further details of the filter syntax and options, go consult ss(8) — it's the source of truth, iykyk.

---

🍓 LOGGING CONFIGURATION 🍓

the pmlogconf(1) configuration file for pmdasockets lives at:

$PCP_VAR_DIR/config/pmlogconf/networking/persocket-linux

(where $PCP_VAR_DIR is typically /var/lib/pcp) and it specifies to log all metrics below network.persocket in the PCP namespace with a default sampling interval of 60 seconds ⏱️✨

want a different interval or a different metric set? just edit that file and then restart the pmlogger service. for details of the syntax, see pmlogconf(1) 💜

---

👑 METRICS 👑

the metrics and metadata supported by pmdasockets correspond to fields reported by ss -noemitauOH and are also available as help text provided by the PMDA. e.g. to list all metrics, metadata descriptors and help text:

# pminfo -fmdtT network.persocket

🫶 note: the PMDA must be installed (enabled) for this command to work correctly — see the installation section above, bestie, don't skip it.

---

🌈 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). classic PCP stuff, we love a configurable config 💅

---

💀 DEBUGGING OPTIONS 💀

the -D or --debug option enables the output of additional diagnostics on stderr to help triage problems — although ngl, the information is sometimes cryptic and primarily intended to provide guidance for developers rather than for end-users 😭. debug is a comma separated list of debugging options; use pmdbg(1) with the -l option to obtain a list of the available debugging options and their meaning.

debugging options specific to pmdasockets are as follows:

• appl0 — loading socket state filter from $PCP_SYSCONF_DIR/filter.conf and source of data 🧚
• appl1 — parsing output from data source 🔍

---

⭐ SEE ALSO ⭐

PCPIntro(1), pmcd(1), pmlogger(1) and ss(8).

---

and that's the whole page, bestie — this was Performance Co-Pilot, PCP, PMDASOCKETS(1), and yes it's literally titled that in the header too. go forth and read your sockets, you absolute icon 💖✨👑