Product SiteDocumentation Site

2.8. Integration of a PMDA

Several steps are required to install (or remove) a PMDA from a production PMCD environment without affecting the operation of other PMDAs or related visualization and logging tools.
The PMDA typically would have its own directory below ${PCP_PMDAS_DIR} into which several files would be installed. In the description in Section 2.8.1, “Installing a PMDA”, the PMDA of interest is assumed to be known by the name newbie, hence the PMDA directory would be ${PCP_PMDAS_DIR}/newbie.

Note

Any installation or removal of a PMDA involves updating files and directories that are typically well protected. Hence the procedures described in this section must be executed as the superuser.

2.8.1. Installing a PMDA

A PMDA is fully installed when these tasks are completed:
  • Help text has been installed in a place where the PMDA can find it, usually in the PMDA directory ${PCP_PMDAS_DIR}/newbie.
  • The name space has been updated in the ${PCP_VAR_DIR}/pmns directory.
  • The PMDA binary has been installed, usually in the directory ${PCP_PMDAS_DIR}/newbie.
  • The ${PCP_PMCDCONF_PATH} file has been updated.
  • The PMCD process has been restarted or notified (with a SIGHUP signal) that the new PMDA exists.
The Makefile should include an install target to compile and link the PMDA (as a DSO, or a daemon or both) in the PMDA directory. The clobber target should remove any files created as a by-product of the install target.
You may wish to use ${PCP_PMDAS_DIR}/simple/Makefile as a template for constructing a new PMDA Makefile; changing the assignment of IAM from simple to newbie would account for most of the required changes.
The Install script should make use of the generic procedures defined in the script ${PCP_SHARE_DIR}/lib/pmdaproc.sh, and may be as straightforward as the one used for the trivial PMDA, shown in Example 2.37, “ Install Script for the Trivial PMDA”:

Example 2.37.  Install Script for the Trivial PMDA

. ${PCP_DIR}/etc/pcp.env
. ${PCP_SHARE_DIR}/lib/pmdaproc.sh

iam=trivial
pmda_interface=2

pmdaSetup
pmdainstall
exit
The variables, shown in Table 2.1, “Variables to Control Behavior of Generic pmdaproc.sh Procedures”, may be assigned values to modify the behavior of the pmdaSetup and pmdainstall procedures from ${PCP_SHARE_DIR}/lib/pmdaproc.sh.

Table 2.1. Variables to Control Behavior of Generic pmdaproc.sh Procedures

Shell Variable
Use
Default
$iam
Name of the PMDA; assignment to this variable is mandatory.
Example: iam=newbie
 
$dso_opt
Can this PMDA be installed as a DSO?
false
$daemon_opt
Can this PMDA be installed as a daemon?
true
$perl_opt
Is this PMDA a perl script?
false
$python_opt
Is this PMDA a python script?
false
$pipe_opt
If installed as a daemon PMDA, is the default IPC via pipes?
true
$socket_opt
If installed as a daemon PMDA, is the default IPC via an Internet socket?
false
$socket_inet_def
If installed as a daemon PMDA, and the IPC method uses an Internet socket, the default port number.
 
$ipc_prot
IPC style for PDU exchanges involving a daemon PMDA; binary or text.
binary
$check_delay
Delay in seconds between installing PMDA and checking if metrics are available.
3
$args
Additional command-line arguments passed to a daemon PMDA.
 
$pmda_interface
Version of the libpcp_pmda library required, used to determine the version for generating help text files.
1
$pmns_source
The name of the PMNS file (by default relative to the PMDA directory).
pmns
$pmns_name
First-level name for this PMDA's metrics in the PMNS.
$iam
$help_source
The name of the help file (by default relative to the PMDA directory).
help
$pmda_name
The name of the executable for a daemon PMDA.
pmda$iam
$dso_name
The name of the shared library for a DSO PMDA.
pmda$iam.$dso_suffix
$dso_entry
The name of the initialization function for a DSO PMDA.
${iam}_init
$domain
The numerical PMDA domain number (from domain.h).
 
$SYMDOM
The symbolic name of the PMDA domain number (from domain.h).
 
$status
Exit status for the shell script
0
In addition, the variable do_check will be set to reflect the intention to check the availability of the metrics once the PMDA is installed. By default this variable is true however the command-line option -Q to Install may be used to set the variable to false.
Obviously, for anything but the most trivial PMDA, after calling the pmdaSetup procedure, the Install script should also prompt for any PMDA-specific parameters, which are typically accumulated in the args variable and used by the pmdainstall procedure.
The detailed operation of the pmdainstall procedure involves the following tasks:
  • Using default assignments, and interaction where ambiguity exists, determine the PMDA type (DSO or daemon) and the IPC parameters, if any.
  • Copy the $pmns_source file, replacing symbolic references to SYMDOM by the desired numeric domain number from domain.
  • Merge the PMDA's name space into the PCP name space at the non-leaf node identified by $pmns_name.
  • If any pmchart views can be found (files with names ending in “.pmchart”), copy these to the standard directory (${PCP_VAR_DIR}/config/pmchart) with the “.pmchart” suffix removed.
  • Create new help files from $help_source after replacing symbolic references to SYMDOM by the desired numeric domain number from domain.
  • Terminate the old daemon PMDA, if any.
  • Use the Makefile to build the appropriate executables.
  • Add the PMDA specification to PMCD's configuration file (${PCP_PMCDCONF_PATH}).
  • Notify PMCD. To minimize the impact on the services PMCD provides, sending a SIGHUP to PMCD forces it to reread the configuration file and start, restart, or remove any PMDAs that have changed since the file was last read. However, if the newly installed PMDA must run using a different privilege level to PMCD then PMCD must be restarted. This is because PMCD runs unprivileged after initially starting the PMDAs.
  • Check that the metrics from the new PMDA are available.
There are some PMDA changes that may trick PMCD into thinking nothing has changed, and not restarting the PMDA. Most notable are changes to the PMDA executable. In these cases, you may need to explicitly remove the PMDA as described in Section 2.8.2, “Removing a PMDA”, or more drastically, restart PMCD as follows:
# ${PCP_RC_DIR}/pcp start
The files ${PCP_PMDAS_DIR}/*/Install provide a wealth of examples that may be used to construct a new PMDA Install script.