--- name: "pmdadm" section: "1" platform: "linux" package: "pcp" version: "7.2.2-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/pmdadm" --- # pmdadm(1) Device Mapper PMDA ## NAME **pmdadm** - Device Mapper PMDA ## SYNOPSIS **$PCP\_PMDAS\_DIR/dm/pmdadm** \[**-D** *debug*\] ## DESCRIPTION **pmdadm** is a Performance Metrics Domain Agent (PMDA) which exports metric values for Device Mapper on the local system. This PMDA collects its data through the [**dmsetup**(8)](/dmsetup/8.md) utility and the dmstats API and requires that the program is installed in order to function. In addition, at least one statistics region must be created using the [**dmstats**(8)](/dmstats/8.md) utility in order to get basic counter values. See below for examples. Note that device-mapper statistics collection is not enabled by default and is not persistent across reboots (unless a system administrator has configured something to run in **rc.local** or equivalent). This is because there are overheads associated with statistics collection. In addition, the **pmdadm** PMDA does not automatically enable any statistics collection because it may not be the only consumer of the data. ## INSTALLATION Install the DM PMDA by using the Install script as root: ``` # cd $PCP_PMDAS_DIR/dm # ./Install ``` To uninstall, the following must be done as root: ``` # cd $PCP_PMDAS_DIR/dm # ./Remove ``` **pmdadm** is launched by [**pmcd**(1)](/pmcd/1.md) and should never be executed directly. The **Install** and **Remove** scripts notify **pmcd** when the agent is installed or removed. ## CONFIGURATION This PMDA uses the dmstats API (the userspace device-mapper support library) to capture device-mapper performance data.\ Using this PMDA, users need the userspace device-mapper support library (libdevmapper) and the userspace command line tool [**dmstats**(8)](/dmstats/8.md). Before device-mapper metrics will be available for PCP, statistics regions have to be created. For example, to enable basic statistics for all local device-mapper logical devices, use the following command: ``` # dmstats create --alldevices ``` `To create statistics regions with specified histogram boundaries, use the following:` ``` # dmstats create --alldevices --bounds histogram_boundaries ``` *Specify the boundaries of a latency histogram to be tracked for the region as a comma* *separated list of latency values. Latency values are given in nanoseconds. An optional* *unit suffix of* **ns**, **us**, **ms**, *or* **s** *may be given after each value to specify units of nanoseconds,* *microseconds, miliseconds or seconds respectively.* *For example,* ``` # dmstats create --alldevices --bounds 10us,30us,50us,70us,90us ``` `Further details and more complex examples can be found in` [**dmstats**(8)](/dmstats/8.md). ## METRICS - **Basic Counters** `Basic counters provide access to the raw counter data from the kernel,` `allowing further processing to be carried out by another program.`\ `The Kernel provides thirteen separate counters for each statistics area.` `The first eleven of these match the counters provided in /proc/diskstats` `or /sys/block/*/*/stat. The final pair provide separate counters for` `read and write time.` - **dmstats.read** `Count of reads completed this interval per device-mapper device.` - **dmstats.reads\_merged** `Count of reads merged this interval per device-mapper device.` - **dmstats.read\_bytes** `Count of kbytes read this interval per device-mapper device.` - **dmstats.reads\_time** `Accumulated duration of all read requests per device-mapper device.` - **dmstats.write** `Count of writes completed this interval per device-mapper device.` - **dmstats.writes\_merged** `Count of writes completed this interval per device-mapper device.` - **dmstats.write\_bytes** `Count of kbytes write this interval per device-mapper device.` - **dmstats.writes\_time** `Accumulated duration of all write requests per device-mapper device.` - **dmstats.in\_progress** `Count of requests currently in progress per device-mapper device.` - **dmstats.io\_ticks** `Nanoseconds spent servicing request per device-mapper device.` - **dmstats.queue\_ticks** `This field is incremented at each I/O start, I/O completion, I/O merge,` `or read of these stats by the number of I/Os in progress multiplied by` `the number of nanoseconds spent doing I/O since the last update of` `this field. This can provide an easy measure of both I/O completion time` `and the backlog that may be accumulating.` - **dmstats.read\_ticks** `Nanoseconds spent servicing reads per device-mapper device.` - **dmstats.write\_ticks** `Nanoseconds spent servicing writes per device-mapper device.`\ - **Histogram fields** `Histograms measure the frequency distribution of user specified I/O latency intervals.` `Histogram bin boundaries are specified when a region is created.`\ `Instance name represents devicename, region id and bin boundaries.` - **dmstats.histogram.hist\_count** `A list of the histogram counts for the current statistics area in order of` `ascending latency value. Each value represents the number of I/Os with` `latency times falling into that bin's time range during the sample period.` - **dmstats.histogram.hist.bins** `The number of latency histogram bins configured for the area.` ## EXAMPLES ``` # dmstats create looptest0 --bounds 10us,30us,50us looptest0: Created new region with 1 area(s) as region ID 0 ``` `# pminfo -f dmstats.read dmstats.histogram.hist_count` `dmstats.read`\ ` inst [0 or "looptest0"] value 4099` `dmstats.histogram.hist_count`\ ` inst [0 or "looptest0:0:0s"] value 1`\ ` inst [1 or "looptest0:0:10us"] value 3752`\ ` inst [2 or "looptest0:0:30us"] value 250`\ ` inst [3 or "looptest0:0:50us"] value 96` ## FILES - **$PCP\_PMDAS\_DIR/dm/help** default help text file for the dm metrics - **$PCP\_PMDAS\_DIR/dm/Install** installation script for the **pmdadm** agent - **$PCP\_PMDAS\_DIR/dm/Remove** undo installation script for the **pmdadm** agent - **$PCP\_LOG\_DIR/pmcd/dm.log** default log file for error messages from **pmdadm** ## 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. ## SEE ALSO [**PCPIntro**(1)](/PCPIntro/1.md), [**pmcd**(1)](/pmcd/1.md), [**pmstore**(1)](/pmstore/1.md), [**dmsetup**(8)](/dmsetup/8.md) and [**dmstats**(8)](/dmstats/8.md).