bionic (1) pmdammv.1.gz

NAME

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

SYNOPSIS

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

DESCRIPTION

       pmdammv  is a Performance Metrics Domain Agent (PMDA) which exports application level performance metrics
       using memory mapped files.  It offers an extremely low overhead instrumentation facility  that  is  well-
       suited  to  long running, mission critical applications where it is desirable to have performance metrics
       and availability information permanently enabled.

       The mmv PMDA exports instrumentation that has been added to an application using the MMV APIs  (refer  to
       mmv_stats_init(3)  and  mmv(5)  for  further  details).  These APIs can be called from several languages,
       including C, C++, Perl, Python, Java (via the separate ``Parfait'' class library)  and  GoLang  (via  the
       separate ``Speed'' library).

       A brief description of the pmdammv command line options follows:

       -d   It  is  absolutely  crucial  that the performance metrics domain number specified here is unique and
            consistent.  That is, 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.

       -l   Location  of the log file.  By default, a log file named mmv.log is written in the current directory
            of pmcd(1) when pmdammv is started, i.e.  $PCP_LOG_DIR/pmcd.  If the log file cannot be  created  or
            is not writable, output is written to the standard error instead.

       -U   User account under which to run the agent.  The default is the unprivileged "pcp" account in current
            versions of PCP, but in older versions the superuser account ("root") was used by default.

INSTALLATION

       Firstly, a security model for interprocess communication between instrumented  applications  and  pmdammv
       (running as a shared library inside pmcd) must be chosen and established.

       This  communication  occurs  through  memory  mapped  files  in  a location known to both pmdammv and the
       instrumented applications.  That location is $PCP_TMP_DIR/mmv,  although  that  is  often  hidden  behind
       application  APIs  such  as  ``Parfait''  and  mmv_stats_init(3).   The permissions set on this directory
       indicate the security model in use.

       The more secure method is to  use  an  existing  unprivileged  group  which  is  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

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

       This  allows  any  application,  running under any user account, to communicate with the PMDA (which runs
       under the "pcp" account by default).  This may not be desirable  for  all  environments  and  one  should
       consider  the  security implications of any directory setup like this (similar classes of issues exist as
       those that affect the system temporary file directories).

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

       If  the  $PCP_TMP_DIR/mmv  directory  does  not  exist, then the ./Install script can be used to create a
       world-writeable 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.

       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.

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

SEE ALSO

       PCPIntro(1), pmcd(1), newgrp(1), setgid(2), mmv_stats_init(3), mmv(5), pcp.conf(5) and pcp.env(5).