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