Ubuntu Manpage: pmfind_check - administration of Performance Co-Pilot discovery

NAME

       pmfind_check - administration of Performance Co-Pilot discovery

SYNOPSIS

       $PCP_BINADM_DIR/pmfind_check [-CNV?]  [-l logfile]

DESCRIPTION

This shell script is used to integrate the Performance Co-Pilot (see PCPIntro(1)) collector service
discovery mechanisms with pmie(1) and pmlogger(1) service administration, such that multiple collector
hosts can be monitored from a single centralized host. It is important to note that the pmfind service
is tightly integrated with the pmie and pmlogger services, and these must also be enabled if the services
are to be started for each collector system that pmfind discovers.

pmfind_check is designed to be enabled via a service management daemon such as systemd(1) on Linux. It
is run from a system timer (either by systemd or by cron on other systems). Once per timer interval
pmfind attempts discovery of PCP collector systems. For each unique system found pmfind_check creates
pmie_check and pmlogger_check control file entries, such that these latter process can manage one pmie
and pmlogger service for each discovered collector system.

When run through systemd these processes will be launched immediately because systemd monitors the
service control files for changes. With systemd one may also initiate an immediate service discovery
with pmfind and pmfind_check by modifying the $PCP_SYSCONF_DIR/pmfind directory in any way.

When run from cron the next (also timer-based) invocation of pmie_check or pmlogger_check will start and
manage the associated pmie and pmlogger processes.

The control file entries created by pmfind_check follow the convention of individual files for each
collector host. The files are named using the (unique) source identifier that pmfind calculates. This
identifier is a hash calculated based on (non-optional) context labels available from every collector
host, and is the same source identifier reported and used by pminfo(1) and pmseries(1).

OPTIONS

The available command line options are:

-C, --containers
This option causes pmfind_check to query each discovered collector system for running containers as
well, which will then be individually monitored.

-l file, --logfile=file
In order to ensure that mail is not unintentionally sent when these scripts are run from cron(8)
diagnostics are always sent to log files. By default, this file is
$PCP_LOG_DIR/pmfind/pmfind_check.log but this can be changed using the -l option. If this log file
already exists when the script starts, it will be renamed with a .prev suffix (overwriting any log
file saved earlier) before diagnostics are generated to the new log file.

-N, --showme
This option enables a ``show me'' mode, where the programs actions are echoed, but not executed, in
the style of ``make -n''. Using -N in conjunction with -V maximizes the diagnostic capabilities for
debugging.

-V, --verbose
The output from the cron execution of the scripts may be extended using the -V option to the scripts
which will enable verbose tracing of their activity. By default the scripts generate no output
unless some error or warning condition is encountered. Using -N in conjunction with -V maximizes
the diagnostic capabilities for debugging.

-?, --help
Display usage message and exit.

CONFIGURATION

       The command line options passed to pmie and pmlogger can be customized via the  $PCP_SYSCONFIG_DIR/pmfind
       configuration file.

       Refer  to the pmie_check and pmlogger_check manual pages for details of the control file format generated
       by pmfind_check.

       By default, each collector system pmie logfile will be created in $PCP_LOG_DIR/pmie/source  and  pmlogger
       archives  will  be  created  below  $PCP_ARCHIVE_DIR/source.  This is consistent with the way pmie(1) and
       pmlogger(1) maintain their activity logs and archive files.

       Typical   crontab(5)   entries   for    periodic    execution    of    pmfind_check    are    given    in
       $PCP_SYSCONF_DIR/pmfind/crontab (unless installed by default in /etc/cron.d already) and shown below.

       # every minute, discover remote PCP services
       *       *       *       *       *       $PCP_BINADM_DIR/pmfind_check
       When  using  systemd(1) on Linux, no crontab entries are needed as the timer and path mechanisms provided
       by systemd are used instead.

FILES

       $PCP_PMIECONTROL_PATH.d
            PCP inference engine control files for each discovered metric source,  typically  one  per  host  or
            container.
            Warning: this files herein must not be writable by any user other than root.

       $PCP_PMLOGGERCONTROL_PATH.d
            PCP logger control files for each discovered metric source, typically one per host or container.
            Warning: this files herein must not be writable by any user other than root.

       $PCP_SYSCONFIG_DIR/pmfind
            default pmie and pmlogger command line arguments, and other parameters passed to pmfind.

       $PCP_SYSCONF_DIR/pmfind/crontab
            sample crontab for automated script execution by root - exists only if the platform does not support
            the /etc/cron.d mechanism.

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).