---
name: "pmdasockets"
section: "1"
platform: "linux"
package: "pcp"
version: "7.2.2-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/pmdasockets"
---

# pmdasockets(1)

sockets statistics PMDA

## 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)](/ss/8.md) 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)](/pmcd/1.md) and should never be executed directly. The Install and Remove scripts notify [**pmcd**(1)](/pmcd/1.md) 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)](/pmstore/1.md) 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)](/ss/8.md).

## LOGGING CONFIGURATION

The [**pmlogconf**(1)](/pmlogconf/1.md) 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)](/pmlogconf/1.md).

## 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)](/pcp.conf/5.md).

## 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 than for end-users. *debug* is a comma separated list of debugging options; use [**pmdbg**(1)](/pmdbg/1.md) 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 |

## SEE ALSO

[**PCPIntro**(1)](/PCPIntro/1.md), [**pmcd**(1)](/pmcd/1.md), [**pmlogger**(1)](/pmlogger/1.md) and [**ss**(8)](/ss/8.md).