Ubuntu Manpage: pcp-ss - 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) PMDA agent. The command
is intended to be reasonably compatible with many of the ss(8) 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), 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) PMDA to be installed
and enabled on the target host (local or remote), see 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).

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) 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)).

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.

       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).

       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).