NAME

       pmdasockets - sockets statistics PMDA

DESCRIPTION

       pmdasockets  is  a Performance Metrics Domain Agent (PMDA) which exports metric values for
       current sockets on the local system.

       This PMDA currently collects its data through the ss(8)  utility  and  requires  that  the
       program is installed in order to function.  This dependency may change in the future.

INSTALLATION

       To install (enable) the sockets PMDA, do the following as root:

           # cd $PCP_PMDAS_DIR/sockets
           # ./Install

       To uninstall (disable), do the following as root:

           # cd $PCP_PMDAS_DIR/sockets
           # ./Remove

       pmdasockets is launched by pmcd(1) and should never be executed directly.  The Install and
       Remove scripts notify pmcd(1) when the agent is installed or removed.

FILTER CONFIGURATION

       The string valued metric network.persocket.filter specifies the ss(1) filter to be applied
       to  optionally  select socket states, IP addresses and other options that pmdasockets will
       collect (to populate it's instance domain).  This is loaded on PMDA startup from the  file
       $(PCP_SYSCONF_DIR)/sockets/filter.conf    (typically   /etc/pcp/sockets/filter.conf)   and
       defaults to state connected meaning only sockets in the connected state will be  included.
       This  can be changed persistently by editing filter.conf as the root user.  The filter can
       also be changed dynamically after the PMDA has started by using pmstore(1) to store a  new
       filter string in the network.persocket.filter metric.  E.g.

           # pmstore network.persocket.filter "state all"

       will change the filter to include sockets in all states.  Note a dynamically stored filter
       is not persisted across PMDA restarts or reboots (edit the config file  for  a  persistent
       change).  For further details of the filter syntax and options, consult ss(8).

LOGGING CONFIGURATION

       The       pmlogconf(1)       configuration       file       for       pmdasockets       is
       $PCP_VAR_DIR/config/pmlogconf/networking/persocket-linux (where $PCP_VAR_DIR is  typically
       /var/lib/pcp)  which  specifies  to  log  all  metrics  below network.persocket in the PCP
       namespace with a default sampling interval  of  60  seconds.   The  logging  interval  and
       metrics  to be logged can be changed by editing that file and then restarting the pmlogger
       service.  For details of the syntax, see pmlogconf(1).

METRICS

       The metrics and metadata supported by pmdasockets correspond  to  fields  reported  by  ss
       -noemitauOH  and  are  also  available as help text provided by the PMDA, e.g. to list all
       metrics, metadata descriptors and help text:

           # pminfo -fmdtT network.persocket

       Note that the PMDA must be installed (enabled) for this command  to  work  correctly,  see
       above.

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

SEE ALSO

       PCPIntro(1), pmcd(1), pmlogger(1) and ss(8).