pcp-ss - report socket statistics

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-hhost 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-aarchive 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

pcpss
            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-hsomehostss-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-asomearchive-S'@Wed16Jun202112:57:21'ss-noemitauO
            Display the same information as the above example, but for the archive somearchive starting  at  the
            given  time  Wed16Jun202112: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-lsomearchive to examine the time bounds of somearchive.

       pcp-asomearchive-O-0ss-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)).

Name

pcp-ss - report socket statistics

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

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

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
       stateconnected,  which  can  be  changed  by storing a new string value in the network.persocket.filter
       metric using pmstore(1), e.g.  pmstorenetwork.persocket.filter"stateestablished".  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.