1PMDAMMV(1)                  General Commands Manual                 PMDAMMV(1)
2
3
4

NAME

6       pmdammv - memory mapped values performance metrics domain agent (PMDA)
7

SYNOPSIS

9       $PCP_PMDAS_DIR/mmv/pmdammv [-d domain] [-l logfile] [-U username]
10

DESCRIPTION

12       pmdammv  is  a  Performance  Metrics  Domain Agent (PMDA) which exports
13       application level performance metrics using memory  mapped  files.   It
14       offers an extremely low overhead instrumentation facility that is well-
15       suited to long running,  mission  critical  applications  where  it  is
16       desirable to have performance metrics and availability information per‐
17       manently enabled.
18
19       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,
22       including  C,  C++,  Perl,  Python,  Java (via the separate ``Parfait''
23       class library) and GoLang (via the separate ``Speed'' library).
24
25       A brief description of the pmdammv command line options follows:
26
27       -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
32       -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
38       -U   User  account  under  which  to run the agent.  The default is the
39            unprivileged "pcp" account in current  versions  of  PCP,  but  in
40            older versions the superuser account ("root") was used by default.
41

INSTALLATION

43       Firstly,  a  security  model  for  interprocess  communication  between
44       instrumented applications and pmdammv  (running  as  a  shared  library
45       inside pmcd) must be chosen and established.
46
47       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
53       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
57            # . /etc/pcp.env
58            # mkdir -m 775 $PCP_TMP_DIR/mmv
59            # chgrp pcp $PCP_TMP_DIR/mmv
60
61       Since  this  method requires instrumented applications to use this non-
62       default group  (see  newgrp(1)  and  setgid(2))  a  common  alternative
63       involves  the  use of a world-writeable $PCP_TMP_DIR/mmv directory with
64       the sticky-bit set (similar to /tmp and /var/tmp, for example).
65
66       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
73       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
77       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
82            # rmdir $PCP_TMP_DIR/mmv
83            # cd $PCP_PMDAS_DIR/mmv
84            # ./Install
85
86       This   installation   process   will   not   overwrite   any   existing
87       $PCP_TMP_DIR/mmv directory.
88
89       If you want to undo the installation, do the following as root:
90
91            # cd $PCP_PMDAS_DIR/mmv
92            # ./Remove
93
94       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

FILES

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

PCP ENVIRONMENT

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

SEE ALSO

121       PCPIntro(1), pmcd(1), newgrp(1), setgid(2), mmv_stats_init(3),  mmv(5),
122       pcp.conf(5) and pcp.env(5).
123
124
125
126Performance Co-Pilot                  PCP                           PMDAMMV(1)
Impressum