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

# pmdaoverhead(1)

performance metrics domain agent (PMDA) exporting resource consumption metrics for groups of processes

## NAME

**pmdaoverhead** - performance metrics domain agent (PMDA) exporting resource consumption metrics for groups of processes

## SYNOPSIS

**$PCP\_PMDAS\_DIR/overhead/pmdaoverhead** \[**-C**\] \[**-c** *config*\] \[**-D** *debug*\] \[**-d** *domain*\] \[**-l** *logfile*\] \[**-R** *interval*\]

## DESCRIPTION

**pmdaoverhead** is a configurable Performance Metrics Domain Agent (PMDA) for exporting resource consumption for groups of related processes.

The **pmdaoverhead** command line options are:

- **-C**

  parse the configuration file(s) and exit after reporting any errors.

- **-c**

  configuration file(s), *config* may be either a file or a directory; in the latter case all the files within *config* are assumed to be configuration files for **pmdaoverhead** and they will all be processed.

  Each configuration file defines one or more \`\`groups'' of processes of interest, using the syntax described in the \`\`CONFIGURATION'' section below.

  By default all configuration files below the *$PCP\_SYSCONF\_DIR/overhead/conf.d/* directory are used.

- **-d**

  It is absolutely crucial that the performance metrics *domain* number specified here is unique and consistent. That is, *domain* should be different for every PMDA on the one host, and the same *domain* number should be used for the same PMDA on all hosts.

- **-l**

  Location of the log file.  By default, a log file named *overhead.log* is written in the current directory of [**pmcd**(1)](/pmcd/1.md) when **pmdaoverhead** is started, i.e. **$PCP\_LOG\_DIR/pmcd**. If the log file cannot be created or is not writable, output is written to the standard error instead.

- **-R**

  The PMDA uses a separate thread to periodically scan all processes to determine which processes are deemed \`\`interesting'' in each group, and extracting resource consumption for those processes. The *interval* (in seconds) determines how often this scanning and resource calculation is done, the default is 60 (seconds).

## CONFIGURATION

Each configuration file defines one or more \`\`groups'' of processes. The file format is simple and follows the following rules.

- 1\.

  Lines beginning with a hash \`\`#'' are treated as comments. More generally, except for the **pattern:** clause described below, all text between a hash and the end of line is treated as a comment.

- 2\.

  White space (spaces or tabs or newlines) are required to separate lexical components.  Spaces and tabs are otherwise ignored. Other than terminating comments and the *regex* in a **pattern:** clause, newlines are also ignored.

- 3\.

  Each group is introduced by a **group** clause that has the form\
   **group** *name* **{** *parameters* **}**\
   where *name* is a unique name for the group across all groups in the **pmdaoverhead** configuration files. As *name* becomes embedded in the Performance Metrics Name Space (PMNS) if must follow the rules for metric name components as described in [**PMNS**(5)](/PMNS/5.md), namely beginning with an alphabetic character, followed by zero or more characters drawn from the alphabetics, numerics and the underscore \`\`\_'' character.

- 4\.

  The *parameters* must include one **id:** clause and one **pattern:** clause.

- 5\.

  An **id:** clause has the form\
   **id:** *ident*\
   where *ident* is a unique identifier number for the group across all groups in the **pmdaoverhead** configuration files. Valid values for *ident* are in the range 0 to 4094 (inclusive).

- 6\.

  A **pattern:** clause has the form\
   **pattern:** *regex*\
   where *regex* is an extended regular expression notation in the style of [**egrep**(1)](/egrep/1.md). The *regex* starts at the first non-whitespace character after **pattern:** and extends to the next newline.

  The processes that are considered to be members of the group are those for which the command name, as reported by\
   `$ pminfo -f proc.psinfo.cmd`\
   is matched by *regex* **plus** all the descendents of those processes. So for example the *regex* **^pmcd$** will match [**pmcd**(1)](/pmcd/1.md) and all the PMDA processes launched by [**pmcd**(1)](/pmcd/1.md) and any of their children, etc.

## INSTALLATION

If you want access to the names, help text and values for the overhead performance metrics, do the following as root:

```
# cd $PCP_PMDAS_DIR/overhead
# ./Install
```

If you want to undo the installation, do the following as root:

```
# cd $PCP_PMDAS_DIR/overhead
# ./Remove
```

**pmdaoverhead** is launched by **pmcd** and should never be executed directly. The Install and Remove scripts notify **pmcd** when the agent is installed or removed.

## FILES

- **$PCP\_PMCDCONF\_PATH**

  command line options used to launch **pmdaoverhead**

- **$PCP\_PMDAS\_DIR/overhead/Install**

  installation script for the **pmdaoverhead** agent

- **$PCP\_PMDAS\_DIR/overhead/Remove**

  undo installation script for the **pmdaoverhead** agent

- **$PCP\_LOG\_DIR/pmcd/overhead.log**

  default log file for error messages and other information from **pmdaoverhead**

- **$PCP\_SYSCONF\_DIR/overhead/conf.d**

  directory containing configuration files for the overhead metrics

## 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 **pmdaoverhead** are as follows:

| | |
| --- | --- |
| Option | Description |
| appl0 | *configfile* parsing |
| appl1 | refresh() start-end timestamps |
| appl2 | /proc selection in refresh() |

## SEE ALSO

[**PCPIntro**(1)](/PCPIntro/1.md), [**pmcd**(1)](/pmcd/1.md), [**pmdaproc**(1)](/pmdaproc/1.md), [**pcp.conf**(5)](/pcp.conf/5.md), [**pcp.env**(5)](/pcp.env/5.md) and [**PMNS**(5)](/PMNS/5.md).