pcp-check - Man Page

manage the configuration of optional PCP components

Synopsis

$pcp-check [-a] [-d] [-l] [-n] [-s] [-v] [-x] [component ...]
$pcp-check [-a] [-c script]] [-d] [-l] [-n] [-s] [-v] [-x]
$PCP_BINADM_DIR/pmcheck ...

Description

The Performance Co-Pilot (PCP) includes a number of core components that are likely to be pre-configured and operational, but it also includes a larger number of components that are not active by default. In the context of pmcheck these components cover services that are typically started as part of the system boot procedure, e.g. pmcd(1), pmlogger(1), pmproxy(1), etc. or optional Performance Metric Domain Agents (PMDAs) that augment the available performance metrics exported by pmcd(1).

pmcheck allows the interrogation of the state of components with the -s, --state option. Components can be activated with the -a, --activate option, or deactivated with the -d, --deactivate option. These three options are clearly mutually exclusive for any single execution of pmcheck, and in the absence of any of them -s is assumed to be the default.

The set of components to be interrogated or configured are specified by the component name(s) from the command line, else all known components in the absence of any component arguments. When one or more component arguments are specified, these may optionally be sh(1) (glob) patterns that are matched against the names of the known components.

The -l, --list option reports on known components. With one or more components each is reported. Without any component arguments the -l option lists all known components, which is simply all the component scripts (see the Component Scripts section below) stored in the $PCP_SHARE_DIR/lib/pmcheck directory. If the -v option is also used, a short description of each requested component is also displayed.

Additional components can be integrated into the pmcheck framework, and the -c, --file option allows an alternate sh(1) script to be used instead of a script associated with a known component.

In concert with the -a or -d options, the -n, --show-me option performs a dry run, showing the sh(1) commands that would be needed to perform the reconfiguration, but no reconfiguration is done. Commands that need to be run as “root” are prefixed with # and other commands are prefixed with $.

The -v, --verbose option increases reporting verbosity.

The -x, --trace option may be used specify that the component scripts are run with -x option to sh(1). This can assist with debugging the failure of a component script or during the development of a new component script, probably also involving the -c option to pmcheck.

The -?, --help option displays a usage message.

As a convience, pmcheck . is an alias for pcp-check.

Component Scripts

The pmcheck framework is extensible, as the set of known components is defined by the names of the component scripts in the $PCP_SHARE_DIR/lib/pmcheck directory.

Each component script needs to abide by the following rules for correct integration with pmcheck:

To assist with component script development, the file $PCP_SHARE_DIR/lib/checkproc.sh may be sourced (after sourcing $PCP_DIR/etc/pcp.env). checkproc.sh provides the following services:

So the following is the simplest possible component script for a system service.

#!/bin/sh
. $PCP_DIR/etc/pcp.env || exit 1
. $PCP_SHARE_DIR/lib/checkproc.sh

_do_args "$@"

if $lflag
then
    [ $verbose -gt 0 ] && echo "my description"
elif $sflag
then
    _ctl_svc state $component
    status=$?
elif $aflag
then
    _ctl_svc activate $component || status=1
elif $dflag
then
    _ctl_svc deactivate $component || status=1
fi

And the following is the simplest possible component script for a PMDA.

#!/bin/sh
. $PCP_DIR/etc/pcp.env || exit 1
. $PCP_SHARE_DIR/lib/checkproc.sh

_do_args "$@"

if $lflag
then
    [ $verbose -gt 0 ] && echo "my description"
elif $sflag
then
    _ctl_pmda state $component
    status=$?
elif $aflag
then
    _ctl_pmda activate $component || status=1
elif $dflag
then
    _ctl_pmda deactivate $component || status=1
fi

Diagnostics

For pmcheck (not the component scripts) the exit status is typically 0, but values of 9 or 99 indicate serious internal botches.

When the -a or -d options are used, the success or failure of the reconfiguration is reported on standard output.

Caveat

Some components have prerequisites that demand additional non-PCP services be installed, configured and operational, e.g. a database server or a key-value server. In these cases, probing the status of the non-PCP service may be subject to some access controls and if pmcheck is run as a non-root user, then the output from -s (the default) may be incomplete or misleading; in these circumstances, running pmcheck as root should provide a more accurate report.

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

init(1), PCPIntro(1), pmcd(1), pmlogger(1), pmproxy(1), sh(1), systemctl(1), pcp.conf(5) and pcp.env(5).

Info

PCP Performance Co-Pilot