'\"macro stdmacro
.\"
.\" Copyright (c) 2020 Red Hat.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.TH PMFIND_CHECK 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmfind_check\f1 \- administration of Performance Co-Pilot discovery
.SH SYNOPSIS
.B $PCP_BINADM_DIR/pmfind_check
[\f3\-CNV?\f1]
[\f3\-l\f1 \f2logfile\f1]
.SH DESCRIPTION
This shell script is used to integrate the Performance Co-Pilot (see
.BR PCPIntro (1))
collector service discovery mechanisms with
.BR pmie (1)
and
.BR pmlogger (1)
service administration, such that multiple collector hosts can be
monitored from a single centralized host.
It is important to note that the
.B pmfind
service is tightly integrated with the
.B pmie
and
.B pmlogger
services, and these must also be enabled if the services are to
be started for each collector system that
.BR pmfind
discovers.
.PP
.B pmfind_check
is designed to be enabled via a service management daemon such as
.BR systemd (1)
on Linux.
It is run from a system timer (either by
.B systemd
or by
.B cron
on other systems).
Once per timer interval
.B pmfind
attempts discovery of PCP collector systems.
For each unique system found
.B pmfind_check
creates
.BR pmie_check
and
.BR pmlogger_check
control file entries, such that these latter process can manage one
.B pmie
and
.B pmlogger
service for each discovered collector system.
.PP
When run through
.B systemd
these processes will be launched immediately because
.B systemd
monitors the service control files for changes.
With
.B systemd
one may also initiate an immediate service discovery with
.B pmfind
and
.B pmfind_check
by modifying the
.IR $PCP_SYSCONF_DIR/pmfind
directory in any way.
.PP
When run from
.B cron
the next (also timer-based) invocation of
.B pmie_check
or
.B pmlogger_check
will start and manage the associated
.B pmie
and
.B pmlogger
processes.
.PP
The control file entries created by
.B pmfind_check
follow the convention of individual files for each collector
host.
The files are named using the (unique) source identifier that
.B 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
.BR pminfo (1)
and
.BR pmseries (1).
.SH OPTIONS
The available command line options are:
.TP 5
\fB\-C\fR
This option causes
.B pmfind_check
to query each discovered collector system for running containers
as well, which will then be individually monitored.
.TP
\fB\-l\fR \fIfile\fR, \fB\-\-logfile\fR=\fIfile\fR
In order to ensure that mail is not unintentionally sent when these
scripts are run from
.BR cron (8)
diagnostics are always sent to log files.
By default, this file is
.B $PCP_LOG_DIR/pmfind/pmfind_check.log
but this can be changed using the
.B \-l
option.
If this log
.I file
already exists when the script starts, it will be renamed with a
.I .prev
suffix (overwriting any log file saved earlier) before diagnostics
are generated to the new log file.
.TP
\fB\-N\fR, \fB\-\-showme\fR
This option enables a ``show me'' mode, where the programs actions are
echoed, but not executed, in the style of ``make \-n''.
Using
.B \-N
in conjunction with
.B \-V
maximizes the diagnostic capabilities for debugging.
.TP
\fB\-V\fR, \fB\-\-verbose\fR
The output from the
.BR cron
execution of the scripts may be extended using the
.B \-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
.B \-N
in conjunction with
.B \-V
maximizes the diagnostic capabilities for debugging.
.TP
\fB\-?\fR, \fB\-\-help\fR
Display usage message and exit.
.SH CONFIGURATION
The command line options passed to
.B pmie
and
.B
pmlogger
can be customized via the
.IR $PCP_SYSCONFIG_DIR/pmfind
configuration file.
.PP
Refer to the
.B pmie_check
and
.B pmlogger_check
manual pages for details of the control file format generated by
.BR pmfind_check .
.PP
By default, each collector system
.B pmie
logfile will be created in
.BI $PCP_LOG_DIR/pmie/ source
and
.B pmlogger
archives will be created below
.BI $PCP_ARCHIVE_DIR/ source\fR.
This is consistent with the way
.BR pmie (1)
and
.BR pmlogger (1)
maintain their activity logs and archive files.
.PP
Typical
.BR crontab (5)
entries for periodic execution of
.B pmfind_check
are given in
.BR $PCP_SYSCONF_DIR/pmfind/crontab
(unless installed by default in
.IR /etc/cron.d
already)
and shown below.
.PP
.nf
.ft CW
# every minute, discover remote PCP services
*       *       *       *       *       $PCP_BINADM_DIR/pmfind_check
.ft 1
.fi
When using
.BR systemd (1)
on Linux,
no
.B crontab
entries are needed as the timer and path mechanisms provided by
.B systemd
are used instead.
.SH FILES
.TP 5
.I $PCP_PMIECONTROL_PATH.d
PCP inference engine control files for each discovered metric source,
typically one per host or container.
.br
.BR Warning :
this files herein must not be writable by any user other than root.
.TP
.I $PCP_PMLOGGERCONTROL_PATH.d
PCP logger control files for each discovered metric source,
typically one per host or container.
.br
.BR Warning :
this files herein must not be writable by any user other than root.
.TP
.I $PCP_SYSCONFIG_DIR/pmfind
default
.B pmie
and
.B pmlogger
command line arguments, and other parameters passed to
.BR pmfind .
.TP
.I $PCP_SYSCONF_DIR/pmfind/crontab
sample crontab for automated script execution by root -
exists only if the platform does not support the
.I /etc/cron.d
mechanism.
.SH PCP ENVIRONMENT
Environment variables with the prefix \fBPCP_\fP are used to parameterize
the file and directory names used by PCP.
On each installation, the
file \fI/etc/pcp.conf\fP contains the local values for these variables.
The \fB$PCP_CONF\fP variable may be used to specify an alternative
configuration file, as described in \fBpcp.conf\fP(5).
.SH SEE ALSO
.BR PCPIntro (1),
.BR pmcd (1),
.BR pmfind (1),
.BR pmie (1),
.BR pmie_check (1),
.BR pminfo (1),
.BR pmlogger (1),
.BR pmlogger_check (1),
.BR pmseries (1),
.BR systemd (1),
.BR crontab (5),
and
.BR cron (8).