# pmdasockets

## NAME



           **pmdasockets** - sockets statistics PMDA
    


## SYNOPSIS



           **$PCP_PMDAS_DIR/sockets/pmdasockets**[**-D** _debug_]
    


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


## DEBUGGING OPTIONS



           The **-D** or **--debug** option enables the output of additional
           diagnostics on _stderr_ to help triage problems, although the
           information is sometimes cryptic and primarily intended to provide
           guidance for developers rather end-users.  _debug_ is a comma
           separated list of debugging options; use pmdbg(1) with the **-l**
           option to obtain a list of the available debugging options and
           their meaning.
    
           Debugging options specific to **pmdasockets** are as follows:
           ┌────────┬───────────────────────────────────────────────────────┐
           │ **Option** │ **Description** │
           ├────────┼───────────────────────────────────────────────────────┤
           │ **appl0** │ loading socket state filter from                      │
           │        │ **$PCP_SYSCONF_DIR/filter.conf** and source of data       │
           ├────────┼───────────────────────────────────────────────────────┤
           │ **appl1** │ parsing output from data source                       │
           └────────┴───────────────────────────────────────────────────────┘
    


* * *