# pmfind_check

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


* * *