1PMDAMMV(1) General Commands Manual PMDAMMV(1)
2
6 pmdammv - memory mapped values performance metrics domain agent (PMDA)
7
9 $PCP_PMDAS_DIR/mmv/pmdammv [-d domain] [-l logfile] [-U username]
10
12 pmdammv is a Performance Metrics Domain Agent (PMDA) which exports ap‐
13 plication level performance metrics using memory mapped files. It of‐
14 fers an extremely low overhead instrumentation facility that is well-
15 suited to long running, mission critical applications where it is de‐
16 sirable to have performance metrics and availability information perma‐
17 nently enabled.
18 The mmv PMDA exports instrumentation that has been added to an applica‐
20 tion using the MMV APIs (refer to mmv_stats_init(3) and mmv(5) for fur‐
21 ther details). These APIs can be called from several languages, in‐
22 cluding C, C++, Perl, Python, Java (via the separate ``Parfait'' class
23 library) and GoLang (via the separate ``Speed'' library).
24 A brief description of the pmdammv command line options follows:
26 -d It is absolutely crucial that the performance metrics domain num‐
28 ber specified here is unique and consistent. That is, domain
29 should be different for every PMDA on the one host, and the same
30 domain number should be used for the same PMDA on all hosts.
31 -l Location of the log file. By default, a log file named mmv.log is
33 written in the current directory of pmcd(1) when pmdammv is
34 started, i.e. $PCP_LOG_DIR/pmcd. If the log file cannot be cre‐
35 ated or is not writable, output is written to the standard error
36 instead.
37 -U User account under which to run the agent. The default is the un‐
39 privileged "pcp" account in current versions of PCP, but in older
40 versions the superuser account ("root") was used by default.
41
43 Firstly, a security model for interprocess communication between in‐
44 strumented applications and pmdammv (running as a shared library inside
45 pmcd) must be chosen and established.
46 This communication occurs through memory mapped files in a location
48 known to both pmdammv and the instrumented applications. That location
49 is $PCP_TMP_DIR/mmv, although that is often hidden behind application
50 APIs such as ``Parfait'' and mmv_stats_init(3). The permissions set on
51 this directory indicate the security model in use.
52 The more secure method is to use an existing unprivileged group which
54 is shared by instrumented applications, pmcd and pmdammv such as the
55 "pcp" group.
56 # . /etc/pcp.env
58 # mkdir -m 775 $PCP_TMP_DIR/mmv
59 # chgrp pcp $PCP_TMP_DIR/mmv
60 Since this method requires instrumented applications to use this non-
62 default group (see newgrp(1) and setgid(2)) a common alternative in‐
63 volves the use of a world-writeable $PCP_TMP_DIR/mmv directory with the
64 sticky-bit set (similar to /tmp and /var/tmp, for example).
65 This allows any application, running under any user account, to commu‐
67 nicate with the PMDA (which runs under the "pcp" account by default).
68 This may not be desirable for all environments and one should consider
69 the security implications of any directory setup like this (similar
70 classes of issues exist as those that affect the system temporary file
71 directories).
72 pmdammv is enabled by default on all modern PCP installations, and thus
74 the names, help text and values for the mmv performance metrics are
75 available without the usual PMDA ./Install process.
76 If the $PCP_TMP_DIR/mmv directory does not exist, then the ./Install
78 script can be used to create a world-writeable sticky-bit-set directory
79 for communication. This is for backwards compatibility, as well as
80 ease of use - to use this mechanism, do the following as root:
81 # rmdir $PCP_TMP_DIR/mmv
83 # cd $PCP_PMDAS_DIR/mmv
84 # ./Install
85 This installation process will not overwrite any existing
87 $PCP_TMP_DIR/mmv directory.
88 If you want to undo the installation, do the following as root:
90 # cd $PCP_PMDAS_DIR/mmv
92 # ./Remove
93 pmdammv is launched by pmcd and should never be executed directly. The
95 Install and Remove scripts notify pmcd when the agent is installed or
96 removed.
97
99 $PCP_PMCDCONF_PATH
100 command line options used to launch pmdammv
101 $PCP_TMP_DIR/mmv
102 directory housing memory mapped value files
103 $PCP_PMDAS_DIR/mmv/help
104 default help text file for the mmv metrics
105 $PCP_PMDAS_DIR/mmv/Install
106 installation script for the pmdammv agent
107 $PCP_PMDAS_DIR/mmv/Remove
108 undo installation script for the pmdammv agent
109 $PCP_LOG_DIR/pmcd/mmv.log
110 default log file for error messages and other information
111 from pmdammv
112
114 Environment variables with the prefix PCP_ are used to parameterize the
115 file and directory names used by PCP. On each installation, the file
116 /etc/pcp.conf contains the local values for these variables. The
117 $PCP_CONF variable may be used to specify an alternative configuration
118 file, as described in pcp.conf(5).
119
121 PCPIntro(1), pmcd(1), newgrp(1), setgid(2), mmv_stats_init(3), mmv(5),
122 pcp.conf(5) and pcp.env(5).
123Performance Co-Pilot PCP PMDAMMV(1)