1PCP-SS(1) General Commands Manual PCP-SS(1)
2
6 pcp-ss - report socket statistics
7
9 pcp [pcp options] ss [ss options]
10
12 pcp-ss reports socket statistics collected by the pmdasockets(1) PMDA
13 agent. The command is intended to be reasonably compatible with many
14 of the ss(8) command line options and reporting formats, but also offer
15 the advantages of local or remote monitoring (in live mode) and also
16 historical replay from a previously recorded PCP archive. Note that
17 since ss(1) has many command line options, many of which are the same
18 as standard PCP command line options as described in PCPIntro(1), the
19 pcp-ss tool should always be invoked by users using the pcp front-end.
20 This allows standard PCP commandline options such as -h, -a, -S, -T,
21 -O, -z, etc to be passed without conflict with ss(1) options. See the
22 EXAMPLES sections below for typical usage and command lines.
23 Live mode uses the pcp -h host option and requires the pmdasockets(1)
25 PMDA to be installed and enabled on the target host (local or remote),
26 see pmdasockets(1) for details on how to enable the sockets PMDA on a
27 particular host. The default source is live metrics collected on lo‐
28 calhost, if neither of the -h or -a options are given.
29 Historical/archive replay uses the pcp -a archive option, where archive
31 is the basename of a previously recorded PCP archive. The archive re‐
32 play feature is particularly useful because socket statistics can be
33 reported for a designated time using the pcp --origin option (which de‐
34 faults to the start time of the archive).
35
37 pcp ss
38 Display default basic socket information for the local host. This
39 includes Netid (tcp, udp, etc), State (ESTAB, TIME_WAIT, etc),
40 Recv-Q and Send-Q queue lengths and the local and peer address and
41 port for each socket.
42 pcp -h somehost ss -noemitauO
44 Display the same basic socket information as above for the host
45 somehost, which may be the default localhost. The additional com‐
46 mand line arguments (-noemitauO) display one line per socket (-O),
47 numeric (-n) service names (default), timer information (-o), ex‐
48 tended socket details (-e), socket memory usage (-m), internal TCP
49 information (-i), both udp (-u) and tcp sockets (-t) and both lis‐
50 tening and non-listening sockets (-a).
51 pcp -a somearchive -S'@Wed 16 Jun 2021 12:57:21' ss -noemitauO
53 Display the same information as the above example, but for the ar‐
54 chive somearchive starting at the given time Wed 16 Jun 2021
55 12:57:21. Note the literal @ prefix is required for an absolute
56 time, see PCPIntro(1) for details. The archive must of course
57 contain data for the requested time. You can use pmdumplog -l
58 somearchive to examine the time bounds of somearchive.
59 pcp -a somearchive -O-0 ss -noemitauO
61 As above, but with an offset of zero seconds (-O-0) before the
62 current end of somearchive, i.e. the most recently logged data.
63 Note that somearchive may be curently growing (i.e. being logged
64 with pmlogger(1)).
65
67 Due to the large number of options supported by pcp-ss, the pcp(1) com‐
68 mand should always be used to invoke pcp-ss in order to specify options
69 such as the metrics source (host or archive) and also (in archive
70 mode), the requested start time or offset, and timezone using the fol‐
71 lowing options:
72 -h, --host
74 The remote hostname to connect to in live mode.
75 -a, --archive
77 The archive file to use for historical sampling
78 -O, --origin
80 The time offset to use within an archive (implies -a)
81 -S, --start
83 The start time (e.g. in ctime(3) format) to use when replaying an
84 archive.
85 -Z, --timezone
87 Use a specific timezone. Since pcp-ss doesn't report timestamps,
88 this only affects the interpretation of an absolute starting time
89 (-S) or offset (-O).
90 -z, --hostzone
92 In archive mode, use the timezone of the archive rather than the
93 timezone on the local machine running pcp-ss. The timezone, start
94 and finish times of the archive may be examined using pmdumplog(1)
95 with the -L option.
96 The above pcp options become indirectly available to the pcp-ss command
98 via environment variables - refer to PCPIntro(1) for a complete de‐
99 scription of these options.
100 The additional command line options available for pcp-ss itself are:
102 -h, --help
104 show help message and exit
105 -V, --version
107 output version information
108 -n, --numeric
110 don't resolve service names
111 -r, --resolve
113 resolve host names
114 -a, --all
116 display all sockets
117 -l, --listening
119 display listening sockets
120 -o, --options
122 show timer information
123 -e, --extended
125 show detailed socket information
126 -m, --memory
128 show socket memory usage
129 -p, --processes
131 show process using socket
132 -i, --info
134 show internal TCP information
135 -s, --summary
137 show socket usage summary
138 -b, --bpf
140 show bpf filter socket information
141 -E, --events
143 continually display sockets as they are destroyed
144 -Z, --context
146 display process SELinux security contexts
147 -z, --contexts
149 display process and socket SELinux security contexts
150 -N, --net
152 switch to the specified network namespace name
153 -4, --ipv4
155 display only IP version 4 sockets
156 -6, --ipv6
158 display only IP version 6 sockets
159 -0, --packet
161 display PACKET sockets
162 -t, --tcp
164 display only TCP sockets
165 -M, --mptcp
167 display only MPTCP sockets
168 -S, --sctp
170 display only SCTP sockets
171 -u, --udp
173 display only UDP sockets
174 -d, --dccp
176 display only DCCP sockets
177 -w, --raw
179 display only RAW sockets
180 -x, --unix
182 display only Unix domain sockets
183 -H, --noheader
185 Suppress header line
186 -O, --oneline
188 socket's data printed on a single line
189
191 The columns in the pcp-ss report vary according to the command line op‐
192 tions and have the same interpretation as described in ss(8).
193 One difference with pcp-ss is that the first line in the report begins
195 with '# Timestamp' followed by the timestamp (in the requested time‐
196 zone, see -z and -Z above) of the sample data from the host or archive
197 source. Following the timestamp is the currently active filter string
198 for the metrics source. In archive mode, the active filter can be
199 changed dynamically, even whilst the archive is being recorded. This
200 is different to ss(8) where the filter is optionally specified on the
201 command line of the tool and is always 'live', i.e. ss(8) does not
202 support retrospective replay. With pcp-ss, the filter is stored in the
203 back-end PMDA, see pmdasockets(1), in the metric network.persocket.fil‐
204 ter. The default filter is state connected, which can be changed by
205 storing a new string value in the network.persocket.filter metric using
206 pmstore(1), e.g. pmstore network.persocket.filter "state established".
207 This will override the persistent default filter, which is stored in a
208 PMDA configuration file and loaded each time the sockets PMDA is
209 started. See pmdasockets(1) for further details and see ss(8) for de‐
210 tails of the filter syntax and examples.
211
213 Environment variables with the prefix PCP_ are used to parameterize the
214 file and directory names used by PCP. On each installation, the file
215 /etc/pcp.conf contains the local values for these variables. The
216 $PCP_CONF variable may be used to specify an alternative configuration
217 file, as described in pcp.conf(5).
218 For environment variables affecting PCP tools, see pmGetOptions(3).
220
222 PCPIntro(1), pcp(1), pmdasockets(1), pmlogger(1), pcp.conf(5) and
223 ss(8).
224Performance Co-Pilot PCP PCP-SS(1)