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

# pmdabash(1)

Bourne-Again SHell trace performance metrics domain agent

## NAME

**pmdabash** - Bourne-Again SHell trace performance metrics domain agent

## SYNOPSIS

**$PCP\_PMDAS\_DIR/bash/pmdabash** \[**-C**\] \[**-D** *debug*\] \[**-d** *domain*\] \[**-l** *logfile*\] \[**-I** *interval*\] \[**-t** *timeout*\] \[**-U** *username*\] *configfile*

## DESCRIPTION

**pmdabash** is an experimental Performance Metrics Domain Agent (PMDA) which exports "xtrace" events from a traced [**bash**(1)](/bash/1.md) process. This includes the command execution information that would usually be sent to standard error with the **set -x** option to the shell.

Event metrics are exported showing each command executed, the function name and line number in the script, and a timestamp. Additionally, the process identifier for the shell and its parent process are exported.

This requires **bash** version 4 or later.

A brief description of the **pmdabash** command line options follows:

- **-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 *bash.log* is written in the current directory of [**pmcd**(1)](/pmcd/1.md) when **pmdabash** 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.

- **-s**

  Amount of time (in seconds) between subsequent evaluations of the shell trace file descriptor(s). The default is 2 seconds.

- **-m**

  Maximum amount of memory to be allowed for each event queue (one per traced process). The default is 2 megabytes.

- **-U**

  User account under which to run the agent. The default is the unprivileged "pcp" account in current versions of PCP, but in older versions the superuser account ("root") was used by default.

## INSTALLATION

In order for a host to export the names, help text and values for the bash performance metrics, do the following as root:

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

As soon as an instrumented shell script (see INSTRUMENTATION selection below) is run, with tracing enabled, new metric values will appear - no further setup of the agent is required.

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

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

**pmdabash** 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.

## INSTRUMENTATION

In order to allow the flow of event data between a [**bash**(1)](/bash/1.md) script and **pmdabash**, the script should take the following actions:

```
#!/bin/sh
source $PCP_DIR/etc/pcp.env
source $PCP_SHARE_DIR/lib/bashproc.sh
pcp_trace on $@       # enable tracing
echo "awoke, $count"
pcp_trace off         # disable tracing
```

The tracing can be enabled and disabled any number of times by the script. On successful installation of the agent, several metrics will be available:

```
$ pminfo bash
bash.xtrace.numclients
bash.xtrace.maxmem
bash.xtrace.queuemem
bash.xtrace.count
bash.xtrace.records
bash.xtrace.parameters.pid
bash.xtrace.parameters.parent
bash.xtrace.parameters.lineno
bash.xtrace.parameters.function
bash.xtrace.parameters.command
```

When an instrumented script is running, the generation of event records can be verified using the [**pmevent**(1)](/pmevent/1.md) command, as follows:

```
$ pmevent -t 1 -x '' bash.xtrace.records
host:      localhost
samples:   all
bash.xtrace.records["4538 ./test-trace.sh 1 2 3"]: 5 event records
  10:00:05.000 --- event record [0] flags 0x19 (point,id,parent) ---
    bash.xtrace.parameters.pid 4538
    bash.xtrace.parameters.parent 4432
    bash.xtrace.parameters.lineno 43
    bash.xtrace.parameters.command "true"
  10:00:05.000 --- event record [1] flags 0x19 (point,id,parent) ---
    bash.xtrace.parameters.pid 4538
    bash.xtrace.parameters.parent 4432
    bash.xtrace.parameters.lineno 45
    bash.xtrace.parameters.command "((  count++  ))"
  10:00:05.000 --- event record [2] flags 0x19 (point,id,parent) ---
    bash.xtrace.parameters.pid 4538
    bash.xtrace.parameters.parent 4432
    bash.xtrace.parameters.lineno 46
    bash.xtrace.parameters.command "echo 'awoke, 3'"
  10:00:05.000 --- event record [3] flags 0x19 (point,id,parent) ---
    bash.xtrace.parameters.pid 4538
    bash.xtrace.parameters.parent 4432
    bash.xtrace.parameters.lineno 47
    bash.xtrace.parameters.command "tired 2"
  10:00:05.000 --- event record [4] flags 0x19 (point,id,parent) ---
    bash.xtrace.parameters.pid 4538
    bash.xtrace.parameters.parent 4432
    bash.xtrace.parameters.lineno 38
    bash.xtrace.parameters.function "tired"
    bash.xtrace.parameters.command "sleep 2"
```

## FILES

- **$PCP\_PMCDCONF\_PATH**

  command line options used to launch **pmdabash**

- **$PCP\_PMDAS\_DIR/bash/help**

  default help text file for the bash metrics

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

  installation script for the **pmdabash** agent

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

  undo installation script for **pmdabash**

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

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

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

| | |
| --- | --- |
| Option | Description |
| appl0 | verbose logging of events of interest |

## SEE ALSO

[**bash**(1)](/bash/1.md), [**pmevent**(1)](/pmevent/1.md) and [**pmcd**(1)](/pmcd/1.md).