PMDADM(1)

💖 PMDADM 💖

okay bestie, gather round, because this is the pmdadm manual page — it lives in the General Commands Manual section (that's section 1, iykyk) and it's all about the Device Mapper PMDA. slay. let's get into it 🎀

---

✨ NAME ✨

pmdadm — the Device Mapper PMDA. that's it, that's the name, short and iconic 💅

---

🌸 SYNOPSIS 🌸

$PCP_PMDAS_DIR/dm/pmdadm [-D debug]

---

🦋 DESCRIPTION 🦋

so, pmdadm is a Performance Metrics Domain Agent (PMDA) — and what a PMDA does is export metric values, and this one exports them for Device Mapper on your local system. local only, bestie, we're not reaching across the network here 🫶

it collects its data through the dmsetup(8) utility and the dmstats API, and fr fr it requires that the program is installed for it to function at all. no dmsetup, no metrics, periodt. also!! you need at least one statistics region created using the dmstats(8) utility before you'll get basic counter values. there's examples further down, don't worry 💖

⚠️ big important note: device-mapper statistics collection is not enabled by default and is not persistent across reboots — unless a system administrator has set up something to run in rc.local or the equivalent. why? because there are overheads associated with statistics collection. also, the pmdadm PMDA does not automatically enable any statistics collection, because it might not be the only consumer of that data. polite of it honestly 🙈

---

🎀 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) and should never be executed directly. like, ever. it's giving "I have a handler" energy. 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, you need the userspace device-mapper support library (libdevmapper) and the userspace command line tool dmstats(8). and 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). go read it, it eats 💅

---

⭐ 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. that's the whole vibe.

• 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

look at those numbers. obsessed 😭💖

---

🍓 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). very configurable, very demure ✨

---

👑 DEBUGGING OPTIONS 👑

the -D or --debug option enables the output of additional diagnostics on stderr to help triage problems — although ngl, 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) with the -l option to obtain a list of the available debugging options and their meaning. go forth and debug, bestie 🔍

---

💀 SEE ALSO 💀

PCPIntro(1), pmcd(1), pmstore(1), dmsetup(8) and dmstats(8).

---

and that's the whole page, no cap 🫶 this one came out of Performance Co-Pilot (that's the source, and the version tag is just PCP, iconic and mysterious) — same title PMDADM(1), same section 1, we just gave it the glow-up it deserved. mwah 💅💖🌸