pmdasockets(1)

1PMDASOCKETS(1)              General Commands Manual             PMDASOCKETS(1)
2
3
4

NAME

6       pmdasockets - sockets statistics PMDA
7

DESCRIPTION

9       pmdasockets  is a Performance Metrics Domain Agent (PMDA) which exports
10       metric values for current sockets on the local system.
11
12       This PMDA currently collects its data through the ss(8) utility and re‐
13       quires that the program is installed in order to function.  This depen‐
14       dency may change in the future.
15

INSTALLATION

17       To install (enable) the sockets PMDA, do the following as root:
18
19           # cd $PCP_PMDAS_DIR/sockets
20           # ./Install
21
22       To uninstall (disable), do the following as root:
23
24           # cd $PCP_PMDAS_DIR/sockets
25           # ./Remove
26
27       pmdasockets is launched by pmcd(1) and should  never  be  executed  di‐
28       rectly.   The  Install and Remove scripts notify pmcd(1) when the agent
29       is installed or removed.
30

FILTER CONFIGURATION

32       The string valued metric network.persocket.filter specifies  the  ss(1)
33       filter  to  be applied to optionally select socket states, IP addresses
34       and other options that pmdasockets will collect (to populate  it's  in‐
35       stance  domain).   This  is  loaded  on  PMDA  startup  from  the  file
36       $(PCP_SYSCONF_DIR)/sockets/filter.conf (typically /etc/pcp/sockets/fil‐
37       ter.conf)  and  defaults to state connected meaning only sockets in the
38       connected state will be included.  This can be changed persistently  by
39       editing  filter.conf  as the root user.  The filter can also be changed
40       dynamically after the PMDA has started by using pmstore(1) to  store  a
41       new filter string in the network.persocket.filter metric.  E.g.
42
43           # pmstore network.persocket.filter "state all"
44
45       will change the filter to include sockets in all states.  Note a dynam‐
46       ically stored filter is not persisted across PMDA restarts  or  reboots
47       (edit the config file for a persistent change).  For further details of
48       the filter syntax and options, consult ss(8).
49

LOGGING CONFIGURATION

51       The   pmlogconf(1)    configuration    file    for    pmdasockets    is
52       $PCP_VAR_DIR/config/pmlogconf/networking/persocket-linux         (where
53       $PCP_VAR_DIR is typically /var/lib/pcp) which specifies to log all met‐
54       rics  below  network.persocket in the PCP namespace with a default sam‐
55       pling interval of 60 seconds.  The logging interval and metrics  to  be
56       logged  can be changed by editing that file and then restarting the pm‐
57       logger service.  For details of the syntax, see pmlogconf(1).
58

METRICS

60       The metrics and metadata supported by pmdasockets correspond to  fields
61       reported by ss -noemitauOH and are also available as help text provided
62       by the PMDA, e.g. to list all metrics, metadata  descriptors  and  help
63       text:
64
65           # pminfo -fmdtT network.persocket
66
67       Note that the PMDA must be installed (enabled) for this command to work
68       correctly, see above.
69

PCP ENVIRONMENT

71       Environment variables with the prefix PCP_ are used to parameterize the
72       file  and  directory  names used by PCP. On each installation, the file
73       /etc/pcp.conf contains the  local  values  for  these  variables.   The
74       $PCP_CONF  variable may be used to specify an alternative configuration
75       file, as described in pcp.conf(5).
76