PMDAMMV(1)

🌸 NAME 🌸

pmdammv — ok so it's a memory mapped values performance metrics domain agent, aka a PMDA, and honestly? iconic. 💅

---

✨ SYNOPSIS ✨

$PCP_PMDAS_DIR/mmv/pmdammv [-D debug] [-d domain] [-l logfile] [-U username]

---

🦋 DESCRIPTION 🦋

So bestie, pmdammv is a Performance Metrics Domain Agent (PMDA, say it with me) that exports application level performance metrics using memory mapped files. It's giving an extremely low overhead instrumentation facility, and it's literally built for long running, mission critical applications where you just want your performance metrics and availability info permanently enabled. No cap. 🔥

The mmv PMDA exports instrumentation that's been added to an application using the MMV APIs — go peek at mmv_stats_init(3) and mmv(5) for the whole tea. And the way these APIs can be called from so many languages?? Obsessed:

• C
• C++
• Perl
• Python
• Java (via the separate ``Parfait'' class library)
• GoLang (via the separate ``Speed'' library)

Here's the lowkey rundown of the pmdammv command line options:

• -d — the performance metrics domain number you put here has to be unique and consistent, it is absolutely crucial, I cannot stress this enough. Like, 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. Consistency is the vibe check. ✨
• -l — location of the log file. By default, a log file named mmv.log gets written in the current directory of pmcd(1) when pmdammv is started, i.e. $PCP_LOG_DIR/pmcd. And if the log file can't be created or isn't writable? Output goes to standard error instead. 💁‍♀️
• -U — the user account under which to run the agent. Default is the unprivileged "pcp" account in current versions of PCP, but in older versions the superuser account ("root") was the default. Throwback, honestly. 🙈

---

🎀 INSTALLATION 🎀

First things first: you gotta pick and establish a security model for the interprocess communication between your instrumented applications and pmdammv (which is running as a shared library inside pmcd). Choose wisely, bestie.

This communication happens through memory mapped files in a location that both pmdammv and the instrumented applications know about. That location is $PCP_TMP_DIR/mmv — although it's often hidden behind application APIs such as ``Parfait'' and mmv_stats_init(3). The permissions set on this directory are what tell you which security model is in use. 👑

The more secure method is to use an existing unprivileged group that's shared by instrumented applications, pmcd and pmdammv, such as the "pcp" group.

# . /etc/pcp.env
# mkdir -m 775 $PCP_TMP_DIR/mmv
# chgrp pcp $PCP_TMP_DIR/mmv

Now, since this method requires instrumented applications to use this non-default group (see newgrp(1) and setgid(2)), a common alternative involves a world-writable $PCP_TMP_DIR/mmv directory with the sticky-bit set — similar to /tmp and /var/tmp, for example.

This lets any application, running under any user account, communicate with the PMDA (which runs under the "pcp" account by default). But ngl, this may not be desirable for all environments, and you should seriously consider the security implications of any directory setup like this — similar classes of issues exist as those that affect the system temporary file directories. Not me telling you twice. 💀

Real talk: that world-writable sticky-bit setup is convenient but it opens the door to the same class of problems that system temporary file directories have. Consider before you commit.

pmdammv is enabled by default on all modern PCP installations, so the names, help text and values for the mmv performance metrics are available without the usual PMDA ./Install process. We love zero effort. 💖

If the $PCP_TMP_DIR/mmv directory doesn't exist, then the ./Install script can be used to create a world-writable sticky-bit-set directory for communication. This is for backwards compatibility, as well as ease of use — to use this mechanism, do the following as root:

# rmdir $PCP_TMP_DIR/mmv
# cd $PCP_PMDAS_DIR/mmv
# ./Install

This installation process will not overwrite any existing $PCP_TMP_DIR/mmv directory. Respectful. 🫶

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

# cd $PCP_PMDAS_DIR/mmv
# ./Remove

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

---

🌈 FILES 🌈

• $PCP_PMCDCONF_PATH — command line options used to launch pmdammv
• $PCP_TMP_DIR/mmv — directory housing memory mapped value files
• $PCP_PMDAS_DIR/mmv/help — default help text file for the mmv metrics
• $PCP_PMDAS_DIR/mmv/Install — installation script for the pmdammv agent
• $PCP_PMDAS_DIR/mmv/Remove — undo installation script for the pmdammv agent
• $PCP_LOG_DIR/pmcd/mmv.log — default log file for error messages and other information from pmdammv

---

💜 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. And the $PCP_CONF variable may be used to specify an alternative configuration file, as described in pcp.conf(5). Slay. ✨

---

🔍 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.

Debugging options specific to pmdammv are as follows:

• appl0 — verbose diagnostics

---

🦄 SEE ALSO 🦄

PCPIntro(1), pmcd(1), newgrp(1), setgid(2), mmv_stats_init(3), mmv(5), pcp.conf(5) and pcp.env(5). Go read them, iykyk. 📚

---

Ok that's the whole page bestie!! This one came from the Performance Co-Pilot (PCP) manual collection — yes, that's the source, that's the version, that's the whole house — and it's the PMDAMMV(1) page, so go forth and instrument literally everything. Mwah. 💖🎀🦋