--- name: "pcp-ss" section: "1" platform: "linux" package: "pcp" version: "7.2.2-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/pcp-ss" --- # pcp-ss(1) report socket statistics ## NAME **pcp-ss** - report socket statistics ## SYNOPSIS **pcp** \[*pcp options*\] **ss** \[*ss options*\] ## DESCRIPTION **pcp-ss** reports socket statistics collected by the [**pmdasockets**(1)](/pmdasockets/1.md) PMDA agent. The command is intended to be reasonably compatible with many of the [**ss**(8)](/ss/8.md) command line options and reporting formats, but also offer the advantages of local or remote monitoring (in live mode) and also historical replay from a previously recorded PCP archive. Note that since **ss**(1) has many command line options, many of which are the same as standard PCP command line options as described in [**PCPIntro**(1)](/PCPIntro/1.md), the **pcp-ss** tool should always be invoked by users using the **pcp** front-end. This allows standard PCP commandline options such as **-h**, **-a**, **-S**, **-T**, **-O**, **-z**, etc to be passed without conflict with **ss**(1) options. See the **EXAMPLES** sections below for typical usage and command lines. Live mode uses the **pcp** **-h** *host* option and requires the [**pmdasockets**(1)](/pmdasockets/1.md) PMDA to be installed and enabled on the target *host* (local or remote), see [**pmdasockets**(1)](/pmdasockets/1.md) 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). ## 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. - **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***).* - **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)](/PCPIntro/1.md) **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)](/pmlogger/1.md)). ## OPTIONS **Due to the large number of options supported by** **pcp-ss**, **the** [**pcp**(1)](/pcp/1.md) **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)](/ctime/3.md) **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)](/pmlogdump/1.md) **with the -L option.** **The above** **pcp** **options become indirectly available to the** **pcp-ss** **command via environment variables - refer to** [**PCPIntro**(1)](/PCPIntro/1.md) **for a complete description of these options.** **The additional command line options available for** **pcp-ss** **itself are:** - **-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** - **-6, --ipv6** **display only IP version 6 sockets** - **-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** ## 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)](/ss/8.md). **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)](/ss/8.md) **where the filter is optionally specified on the command line of the tool and is** **always 'live', i.e.** [**ss**(8)](/ss/8.md) **does not support retrospective replay.** **With** **pcp-ss**, **the filter is stored in the back-end PMDA, see** [**pmdasockets**(1)](/pmdasockets/1.md), **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)](/pmstore/1.md), **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)](/pmdasockets/1.md) **for further details and see** [**ss**(8)](/ss/8.md) **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)](/pcp.conf/5.md).** **For environment variables affecting PCP tools, see [pmGetOptions(3)](/pmGetOptions/3.md).** ## SEE ALSO [**PCPIntro**(1)](/PCPIntro/1.md), [**pcp**(1)](/pcp/1.md), [**pmdasockets**(1)](/pmdasockets/1.md), [**pmlogger**(1)](/pmlogger/1.md), [**pcp.conf**(5)](/pcp.conf/5.md) **and** [**ss**(8)](/ss/8.md).