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

Performance Co-Pilot                                   PCP                                        PMDASOCKETS(1)